> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/development/creating-a-package.md).

# Creating a package

A package is a collection of metadata grouped together in a directory, and defined by an entry in your sfdx-project.json (Project Manifest).

```json
// A sample sfdx-project.json with a package
{
  "packageDirectories": [
    {
      "path": "src/my-package",
      "package": "my-package",
      "versionNumber": "1.0.0.NEXT"
    }
  ]
}
```

Each package in sfp must have the following attributes as the minimum:

| Attribute     | Required | Description                                                     |
| ------------- | -------- | --------------------------------------------------------------- |
| path          | yes      | Path to the directory that contains the contents of the package |
| package       | yes      | The name of the package                                         |
| versionNumber | yes      | The version number of the package                               |

{% hint style="info" %}
sfp will not consider any entries in your sfdx-project.json for its operations if it is missing 'package' or 'versionNumber' attribute.
{% endhint %}

## Package Types

By default, sfp treats all entries in sfdx-project.json as [Source Packages](/flxbl/sfp/concepts/supported-package-types/source-packages.md). You can create different types of packages depending on your needs:

| Package Type     | Description                                 |
| ---------------- | ------------------------------------------- |
| Source Package   | Default package type for deploying metadata |
| Unlocked Package | Versioned, upgradeable package              |
| Data Package     | Package for data migration                  |
| Diff Package     | Package containing only changed components  |

An unlocked package can additionally be created as **org-dependent**. That is a property of an unlocked package, not a package type of its own.

## Creating Packages

The `sfp package create` commands write the package entry into `sfdx-project.json` and register the package with the sfp server. Each of them takes `--repository` — the repository the package belongs to, as `owner/repo` for GitHub and GitLab or `org/project/repo` for Azure DevOps. It defaults to the `GITHUB_REPOSITORY` or `GITLAB_REPOSITORY` environment variable, so it can be omitted in a pipeline but has to be supplied when running locally.

These flags are common to all four commands:

* `-n, --name` (required): Package name
* `-r, --path` (required): Directory path for the package
* `-d, --description`: Package description
* `--domain`: Name of the release config the package belongs to — takes a value, for example `--domain release-config-frameworks`
* `--repository`: Repository identifier, as described above
* `-b, --branch`: Branch to register the package against
* `--no-insert`: Do not write the entry into `sfdx-project.json`
* `--insert-after`: Insert the entry after a named package

### Source Package

```bash
sfp package create source -n "my-source-package" -r "src/my-package" --repository myorg/myrepo

# Attached to a release config
sfp package create source -n "my-source-package" -r "src/my-package" --domain release-config-sales --repository myorg/myrepo
```

Takes the common flags only.

### Unlocked Package

```bash
sfp package create unlocked -n "my-unlocked-package" -r "src/my-package" --repository myorg/myrepo

# Org-dependent unlocked package
sfp package create unlocked -n "my-package" -r "src/my-package" --org-dependent --repository myorg/myrepo

# Without a namespace
sfp package create unlocked -n "my-package" -r "src/my-package" --no-namespace --repository myorg/myrepo
```

**Additional flags:**

* `--org-dependent`: Create the package as org-dependent
* `--no-namespace`: Create the package without a namespace
* `--error-notification-username`: Username to notify on package creation errors

### Data Package

```bash
sfp package create data -n "my-data-package" -r "data/my-data-package" --repository myorg/myrepo
```

Takes the common flags only.

{% hint style="info" %}
Ensure your data package directory contains an export.json and the required CSV files. See [Data Packages](/flxbl/sfp/concepts/supported-package-types/data-packages.md) for details.
{% endhint %}

### Diff Package

```bash
sfp package create diff -n "my-diff-package" -r "src/my-diff-package" --commit-id "baseline-commit-id" --repository myorg/myrepo
```

**Additional flags:**

* `--commit-id`: Commit the diff is calculated from

## Best Practices

1. **Use descriptive names**: Package names should clearly indicate their purpose
2. **Organize by domain**: Group related packages using domains
3. **Version consistently**: Version numbers are four-part — `MAJOR.MINOR.PATCH.BUILD`, where the build segment is usually `NEXT`
4. **Choose the right type**:
   * Source packages for most metadata
   * Unlocked packages for distributed, versioned components
   * Data packages for reference data
   * Diff packages for selective deployments

## Next Steps

* [Defining a Domain](/flxbl/sfp/development/defining-a-domain.md) - Organize packages into domains
* [Building Artifacts](/flxbl/sfp/building-artifacts/overview.md) - Build deployable artifacts from packages
* [Package Types](/flxbl/sfp/concepts/supported-package-types.md) - Learn more about different package types


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/development/creating-a-package.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.