Development workflow

You need Node.js 20.x and npm to build Hummingbird. For the full list of tools, see Requirements. For setting up a local PrestaShop instance, see Environment setup.

Script commands

Command Purpose
npm ci Install exact dependency versions from the lockfile
npm run build Compile SCSS and TypeScript into production assets
npm run watch Watch for file changes and recompile automatically
npm run lint Run ESLint and Stylelint
npm run format Run Prettier
npm run storybook Launch Storybook component explorer

Run npm ci first to install dependencies, then npm run build to compile. During development, npm run watch recompiles on every file save.

Hummingbird includes a .nvmrc file. If you use nvm, run nvm use in the theme directory to automatically switch to the correct Node.js version.

Docker environment

Hummingbird includes Docker Compose configurations that mount your theme directory automatically. See Environment setup for setup instructions and available images.

For the full Docker configuration details, see the Hummingbird README.

Storybook

Hummingbird ships with Storybook for isolated component development. Start it with:

npm run storybook

This opens a component explorer where you can develop and review UI components without a running PrestaShop instance.

Troubleshooting

If styles or templates don’t update during development:

PrestaShop cache

In the Back Office under Advanced Parameters > Performance:

  • Smarty: set Force compilation to Yes and Cache to No
  • CCC (Combine, Compress, Cache): disable all options to prevent CSS/JS merging
For more development mode settings, see Configure for development.

Webpack watch not recompiling

If npm run watch is running but compiled files are not updating:

  • Verify the watch process has no errors in its terminal output
  • Check that you are editing files inside src/. Files in assets/ are the compiled output and should not be edited directly