---
title: "Packaging Guidelines"
description: "This section describes the requirements we have for all GitHub repositories,
and npm modules we maintain."
canonical_url: "https://flowfuse.com/handbook/engineering/packaging/"
---

> Index of every page on this site: [llms.txt](https://flowfuse.com/llms.txt)

# Packaging Guidelines

This section describes the requirements we have for all GitHub repositories,
and npm modules we maintain.

To help ensure all of the requirements are met, an issue should be raised in
[`FlowFuse/admin`](https://github.com/FlowFuse/admin/issues/new/choose)
using the `New Repository Checklist` and then worked through.

## GitHub projects

### Naming

- FlowFuse Components should start with `flowfuse-`
- If a Node-RED plugin/node should start with `nr-`
- FlowFuse Certified nodes should start with `ffcn-`
- Installers or Orchestration projects are named without the leading `flowfuse-` e.g. `installer` or `helm`

### Settings

- A rule should be added under the projects `settings/branches` to prevent pushing directly to the `main` branch
- The `Do not allow bypassing the above settings` rule should be ticked when creating the branch rules

### Content

All Git Repositories must contain the following files:

- `README.md`
- `LICENSE`

### Linting

All code repositories should be using ESLint V9 or greater and adopt our standard linting rules by copying
`eslint.config.mjs` from the [FlowFuse/.github repository](https://github.com/FlowFuse/.github/blob/main/eslint.config.mjs).

If a repository has any additional requirements for linting, such as handling Vue
code, then additional plugins can be added.

We stick closely to the [StandardJS](https://standardjs.com/), with one exception - 4 spaces not 2.

#### Scripts for linting in package.json

We add 2 common scripts for linting:

1. `lint`
2. `lint:fix`

Below is a typical example:

```json
"scripts": {
        // ...other scripts...
        "lint": "eslint -c eslint.config.mjs",
        "lint:fix": "eslint -c eslint.config.mjs --fix"
    },
```

### Notifications

Repositories should be added to the appropriate Slack channel. For core code repositories,
this would be in the `#gh-flowfuse` channel.

To create a subscription, go to that channel and type the message:

```text
/github subscribe FlowFuse/NAME-OF-REPO comments reviews
```

This will subscribe to any notifications covering: `issues`, `pulls`, `commits`, `releases`, `deployments`, `comments` and `reviews`.

### Workflows

#### Project Automation

All repositories must have the Project Automation workflow added, including non-code repositories where issues are created. This is done
by adding `.github/workflows/project-automation.yml` ([template](https://raw.githubusercontent.com/FlowFuse/.github/refs/heads/main/.github/workflows/project-automation.yml)).
This workflow will ensure any opened issues are automatically added to the [Product board](https://github.com/orgs/FlowFuse/projects/3) where it can be triaged and prioritised.

#### Prepare and Publish a Release

For any repositories that contain modules to be published to public npm, they should also
have a copy of `.github/workflows/release-please.yml` ([template](https://raw.githubusercontent.com/FlowFuse/nr-assistant/refs/heads/main/.github/workflows/release-please.yaml)) and `.github/workflows/release-publish.yml` ([template](https://raw.githubusercontent.com/FlowFuse/flowfuse/refs/heads/main/.github/workflows/release-publish.yml)).

The `release-please` tool that is used by the `Prepare release` workflow requires also a configuration file, typically `.release-please-config.json`, to define how releases should be managed for the repository, and the manifest file that holds the version information for the module. Since the tool relies on the Conventional Commits specification, the ["Lint Pull Request Title"](#pull-request-title-linting) workflow needs to be set as a required check in the repository to ensure commit messages follow the Conventional Commits format.
A complete example of this implementation can be found in the [following pull request](https://github.com/FlowFuse/node-red-dashboard/pull/2275).

For modules being published to the Certified Nodes npm registry this `release-publish.yml` file should be edited to point to the `https://registry.flowfuse.com` registry and to make use of the correct token.

An example can be found in the [flowfuse/nr-mcp-server-nodes](https://github.com/FlowFuse/nr-mcp-server-nodes/blob/main/.github/workflows/release-publish.yml) project. The `CERTIFIED_NODES_PUBLISH_TOKEN` should be added to the projects Secrets and can be found in 1Password.

This workflow will publish to npm whenever the repository is tagged with a `vX.Y.Z` format
tag.

Note that each repository may have slightly different pre-publish requirements - for
example if there is a build step or not. You may need to customise the workflow
to match what is needed.

#### Pull Request Title Linting

To ensure that all pull requests follow the Conventional Commits specification, the "Lint Pull Request Title" workflow should be added to the repository. This is typically done by adding `.github/workflows/lint-pr-title.yml` ([template](https://raw.githubusercontent.com/FlowFuse/nr-assistant/refs/heads/main/.github/workflows/lint-pr-title.yaml)) to the repository. This workflow will check the title of each pull request and enforce the required format. As mentioned in the previous paragraph, it should be set as a required check for each pull request in the repository to ensure commit messages follow the Conventional Commits format.

#### Static Application Security Testing

For any repository that contains code, the Static Application Security Testing workflow should be added.
This is done by adding `.github/workflows/sast.yml` ([template](https://raw.githubusercontent.com/FlowFuse/flowfuse/refs/heads/main/.github/workflows/sast-scan.yml)) to the repository. This workflow will run on any pull request and will scan the code for any known security vulnerabilities. By default, scan results are added to The GitHub Advanced Security tab of the repository, but can be configured to also post comments on the pull request if vulnerabilities are found (see reusable workflow for details).

### Labels

We have a standard set of labels that should be applied to all repositories. This
ensures we have a consistent approach to planning and tracking of work.

The definitive list of labels is maintained [here](https://github.com/FlowFuse/.github/blob/main/labels.json)
and are synchronized across all repositories via GitHub Actions.

- Type: `epic`, `story`, `task`, `bug`, `artwork`
- Sizing: `XS - 1`, `S - 2`, `M - 3`, `L - 5`, `XL - 8`, `XXL - 13`
- Area: `area:docs`, `area:db`, `area:migration`, `area:frontend`, `area:api`, `area:device`, `area:billing`, `area:infrastrucutre`, `area:install`, `design`
- Priority: `priority:high`, `priority:medium`, `priority:low`
- Status: `blocked`, `consideration`
- Product Scope: `scope:devices`, `scope:enterprise`, `scope:node-red`, `scope:collaboration`
- Other: `good first issue`, `upstream`, `needs-triage`, `headline`, `backport`, `research`

New repositories must be added to the list in [`flowforge-repositories.yml`](https://github.com/FlowFuse/.github/blob/main/flowforge-repositories.yml),
and then the [Synchronize Labels](https://github.com/FlowFuse/.github/actions/workflows/sync-labels.yml) action manually run.

## NPM packages

### Naming

*Note:* we are migrating to the `@flowfuse` scope of packages. See [this issue](https://github.com/FlowFuse/admin/issues/211)
for details. This section of the handbook will be updated as part of the migration.

- npm packages should be scoped as either `@flowfuse/` (pubilc) `@flowfuse-nodes/` (restricted) or `@flowfuse-certified-nodes/` (certified nodes)

Node-RED plugins should start with `nr-` e.g.

- @flowforge/nr-storage
- @flowforge/nr-auth

FlowFuse plugins should start with `forge-` e.g.

- @flowforge/forge-driver-localfs
- @flowforge/forge-driver-docker
- @flowforge/forge-driver-k8s

### Content

The `package.json` must contain the following keys

- description
- repository
```text
"repository": {
   "type": "git",
   "url": "git+https://github.com/FlowFuse/flowforge.git"
},
```
- homepage
```text
"homepage": "https://github.com/FlowFuse/flowforge#readme",
```
- bugs
```text
"bugs": {
    "url": "https://github.com/FlowFuse/flowfuse/issues"
},
```
- license

  - Apache-2.0
  - SEE LICENSE IN ./LICENSE
- author
```text
"author": {
    "name": "FlowFuse Inc."
},
```
- engines
```text
"engines": {
  "node": ">=16.x"
}
```

Packages with `@flowfuse-nodes/` or `@flowfuse-certified-nodes/` scopes should also contain the `registry` section.

- publishConfig
```text
"publishConfig": {
   "registry": "https://registry.flowfuse.com"
}
```

### Package Version Numbering

Package numbers should follow the Semantic Versioning Scheme as laid out on [semver.org](https://semver.org/).

Each component will stay in step with the core flowforge/flowforge release numbering for `major.minor` but will increment their own `fix` values as needed. e.g. On release of v0.2.0 all components will tag and release v0.2.0, but can independently release v0.2.1 as needed.

Major and minor releases will follow the schedule laid out in the [Cadence](https://flowfuse.com/handbook/engineering/project-management#cadence) section of the handbook.

A Fix release can be made at any time, depending on the best judgement of the engineer making the fix but requires a review by another team member.

The process for making a release is documented [here](https://flowfuse.com/handbook/engineering/releases/process).

### Adding NPM packages to Stacks

As we build more FlowFuse specific nodes we will need to add these to the Stacks

#### Localfs

Currently bundled packages for the localfs driver need to be added to the [nr-launcher](https://github.com/FlowFuse/nr-launcher) `package.json`  and the path to the node needs to be added to the `nodesDir` array in the `lib/launcher.js` file (around line 70). This will be updated in the next release to be controlled by the [driver-localfs](https://github.com/FlowFuse/driver-localfs) project

#### Docker

Any nodes or themes should be added to the `package.json` in `node-red-container/` directory of the [docker-compose](https://github.com/FlowFuse/docker-compose) project

#### K8s

Any nodes or themes should be added to the `package.json` in `node-red-container/` directory of the [helm](https://github.com/FlowFuse/helm) project

## Sitemap

See the full [sitemap](https://flowfuse.com/sitemap.md) for all pages.
