🗺️ strapi-sea

ℹ️ About

This project contains needed configs, scripts and patches for node modules to allow run Strapi as a node.js Single Executable Application (SEA).

The Strapi app was generated by

npx create-strapi-app@5.33.3

and choose "sqlite" db.

🚀 Getting Started

🛠️ Prerequisites

• 📦 Node.js >= 20.x
• 🔧 npm >= 10.x

📋 Installation Steps

1. Prepare your project

Attention: you should first commit / stash all you changed files so you can verify the SEA specific changes after apply them.

The easiest way to prepare your project to use SEA is to apply the corresponding strapi-sea-v<strapi version>.patch to your workspace by download it from the Release page and call git apply --reject strapi-sea-vX.X.X.patch (--reject create .rej files for all not applyable chunks):

strapiVersion=$(npm list @strapi/strapi --depth=0 | grep @strapi/strapi | sed 's/^.*@\([0-9.]\+\).*$/\1/' | head -1)
patchName="strapi-sea-v${strapiVersion}.patch"
wget "https://github.com/swerder/strapi-sea/releases/download/v${strapiVersion}/${patchName}"
git apply --reject "${patchName}"

Install the new added packages

npm install

Alternative do it manually

Copy the files patches/*, scripts/*, bundle_files/*, src/utils/*, src/server.ts and the new scripts/configs in package.json to your project.

Install the needed packages

npm install --save-dev node-loader null-loader tsx webpack webpack-cli

2. Configure the logic

In the package.json you can define the configs:

• executableName: the name that the executable and zip will have.

If you want to use a different db system then sqlite for the SEA application you have to comment the corresponding lines in bundle_files/webpack.config.mjs, adjust bundle_files/.env.exec.example with the needed informations and install all required npm modules.

3. Create your Strapi application

Do what you want with the Strapi project to fulfill your application goal (if not done already), and verify all work as expected on normal npm run start.

4. Prepare minimal DB seeds

Adjust bundle_files/seed-config.json to add the minimal required db entries and relations for your application to work.

5. Build the SEA executable for your application

Attention: the bundled and exec folders are always deleted on new build so make sure you update seed-config.json in bundle_files directory to keep it.

npm run build:all

6. Test SEA executable for your application

npm run setup:sea
npm run start:sea

If you use windows

The start scripts in the package.json only work for unix based systems. For Windows do:

cd exec
startServer.cmd --setup
startServer.cmd

7. Release your application

• Update your manual created CHANGELOG.md if any.

• Update the package release version:

  newVersion=<version>
  npm version ${newVersion} --no-git-tag-version
  git add package.json package-lock.json CHANGELOG.md
  git commit -m "Prepare release version ${newVersion}"
  git push

• Merge application to your main branch in cli or by pull request.

  For do it in cli

  current_branch=$(git rev-parse --abbrev-ref HEAD)
  git checkout main
  git merge $current_branch
  git push

• Create release tag v<version> and push it.

  newVersion=<version>
  git tag v${newVersion}
  git push origin v${newVersion}

• The github action start to build all executables and create a draft release for it.

Debugging Webpack

For debugging what files are found by my adjustments for webpack you can set some environment Variables:

export DEBUG_PRINT_WEBPACK_CONTEXT=1
export DEBUG_PRINT_CONFIG=1
export DEBUG_PRINT_STRAPI_MODULE=1
npm run start:sea

CommonJS vs ESModule

The patches adjust the required files of strapi in the js (CommonJS) and mjs (ESModule) files so both variants would work. The webpack and sea configs check the type property in package.json to determine if it's module syntax or not. You have to set compilerOptions.module property in tsconfig.json correspondingly to "commonjs" or "es2022"/"esnext" based on the package.json settings.

🤝 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs
• 🔧 Submit pull requests
• 📚 Improve documentation

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Known issues

For unused node_modules that pop up as missing errors in webpack build, I add them as "ignored" in webpack config.

In the most cases I fix webpack warnings by implement a specific logic to load the required files.

In "umzug" I prevent to pack the cli part and disable the "glob" logic to define migration files.

In "knex" I disable the dynamic loading AbstractMigrationsLoader.getFile() and FsSeeds.getSeed() functions.

In "@strapi/core" and "@strapi/admin" I prevent "@strapi/typescript-utils" from being loaded and mock the functions.

Only ico and png favicon in main dir are loaded, no alternative path can be defined, see node_modules/@strapi/core/dist/middlewares/favicon.js

The webpack build may still show different warnings in your codebase because off dynamic loading of modules. Webpack load all libraries that are referenced in the code, also if they are not realy used. If the warnings lead to problems on your side you can address them similar to the way I do it on the strapi modules (see patches). Or prevent them to be loaded at all(see patches e.g umzug/knex).