Express framework

The Express extension streamlines the process of building Express application rocks. It facilitates the installation of Express application dependencies, including Node.js and npm, inside the rock.

Additionally, it transfers your project files to /app within the rock.

The extension discovers the location of the package.json, but the extension can only package a single application.

By default, the system foundation, or base, is set as bare to generate a lightweight image.

Note

The Express extension is compatible with the bare, ubuntu@24.04 and ubuntu@26.04 bases. Support for Ubuntu 26.04 LTS is experimental.

Part names added by the extension vary by Ubuntu version. On Ubuntu 24.04 LTS, write extension/part. On Ubuntu 26.04 LTS and higher, write extension.part. For rocks with base: bare, follow the convention for the configured build-base.

Use the extension

Declare the extension in rockcraft.yaml:

rockcraft.yaml
extensions:
  - expressjs-framework

You can generate this project file by running rockcraft init --profile expressjs-framework in the application’s directory. To inspect the parts, services, and other configuration contributed by the extension, run rockcraft expand-extensions in the same directory as the rockcraft.yaml file.

Project requirements

There are three requirements to be able to use the expressjs-framework extension:

  • The application should reside in the app directory.

  • The application should have a package.json file.

  • The package.json file should define the start script.

For more information, see the npm documentation.

There are two requirements to be able to use the expressjs-framework extension:

  • The application should have a package.json file in the same directory as rockcraft.yaml file or one directory below the rockcraft.yaml file.

  • The package.json file should define the start script.

For more information, see the npm documentation.

If the application defines a build script in its package.json file, it is recommended to have a files array describing the entries to be included or have an appropriate .npmignore file to exclude entries not required at runtime. If the files array is not defined and .npmignore does not exist, only the dist/ directory will be packaged.

Node.js version

The npm-include-node and npm-node-version keys specify the version of Node.js to be installed. For example:

rockcraft.yaml
parts:
  expressjs-framework/install-app:
    npm-include-node: true
    npm-node-version: 20.12.2
rockcraft.yaml
parts:
  expressjs-framework.install-app:
    npm-include-node: true
    npm-node-version: 20.12.2

For more examples of the npm-node-version key, see npm plugin.

If you don’t customize the version of Node.js, it will be installed from the Ubuntu package repository. The exact version differs between Ubuntu releases. Check the nodejs package for the Ubuntu release you’re using (for example, Noble).

Additional runtime packages

Installing additional runtime packages is currently unsupported.

Database migration

A migrate script placed in the application directory, that is, the directory containing the package.json file, is copied into the rock’s /app directory together with the rest of the application. The 12-factor charm runs the migration script before the application starts, so make sure the script is executable, idempotent and safe to run on multiple units concurrently.

A migrate.sh script for an Express application typically runs the migration command of an ORM library, for example:

#!/bin/bash
# for Prisma:
npx prisma migrate deploy
# for Knex:
npx knex migrate:latest