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, 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:
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 four requirements to be able to use the expressjs-framework
extension:
The application should reside in the
appdirectory.The application should have a
package.jsonfile.The
package.jsonfile should define thestartscript.The
package.jsonfile should define thenamefield.
For more information, see the npm documentation.
There are three requirements to be able to use the expressjs-framework
extension:
The application should have a
package.jsonfile in the same directory asrockcraft.yamlfile or one directory below therockcraft.yamlfile.The
package.jsonfile should define thestartscript.The
package.jsonfile should define thenamefield.
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, Rockcraft warns that it will package all files, not only those in the dist/ directory.
With a build script, the whole dist directory is always included,
whatever the files array or the .npmignore file say.
Node.js version¶
The npm-include-node and npm-node-version keys
specify the version of Node.js to be installed. For example:
parts:
expressjs-framework/install-app:
npm-include-node: true
npm-node-version: 20.12.2
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¶
The extension doesn’t provide a dedicated part for additional packages. To
install extra packages, add your own part with the nil plugin and list the
packages under stage-packages.
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.
If package.json has a files array or the project has a .npmignore
file, make sure it includes the migration script. Otherwise the rock won’t
contain it.
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