Skip to content

Centralized NPM Dependencies for Multi-Theme Projects

This guide explains how to maintain a single Node.js/NPM installation at the Magento project root to build multiple Hyvä themes. This approach mirrors workflows familiar from Luma-based SCSS tooling like Snowdog Frontools, where all build dependencies are managed centrally rather than duplicated in each theme directory.

Advanced Configuration

This setup requires understanding of Node.js package management, Tailwind CSS content configuration, and multi-theme build workflows. Basic setup support is not provided—contact support only for bugs, not configuration assistance.

When to Use This Approach

Use centralized NPM dependencies when managing multiple Hyvä themes that share build tooling. For simpler use cases where themes only need to share CSS variables or utility classes, the Shared CSS documentation offers a less complex solution.

Using System-Wide Global Packages

Some development tools like BrowserSync work well as system-wide global installations, available to all projects on your machine. This is appropriate for CLI tools you use across many projects.

Installing BrowserSync Globally

Remove BrowserSync from your theme's local dependencies and install it globally:

# Remove from theme's package.json
npm rm browser-sync

# Install globally (available system-wide)
npm install -g browser-sync

After global installation, the browser-sync command is available in any directory without per-theme installation.

Global Installation Considerations

Not all packages are suitable for global installation. Build tools like Tailwind CSS should remain project-local to ensure version consistency across team members and CI/CD environments.

Project-Root NPM Installation

Move all NPM dependencies to the Magento project root, enabling centralized management of build tooling for multiple themes. This mirrors the Luma/Frontools workflow where a single package.json at the project root contains build scripts for all themes.

Alternative: Wrapper Scripts

Instead of centralizing dependencies, you can create bash or PHP scripts that execute npm run build within each theme directory. This approach keeps dependencies isolated per-theme while providing a single entry point for builds.

Setting Up Centralized Dependencies

Step 1: Copy Build Configuration to Project Root

Tailwind v3 instructions

The following instructions reference postcss.config.js, that is only present with Tailwind v3 based themes. For Tailwind v4 projects adjust the file list accordingly.

Copy the following files from any Hyvä theme's web/tailwind/ directory to your Magento project root:

  • package.json — NPM dependencies and scripts
  • package-lock.json — Locked dependency versions
  • browser-sync.config.js — BrowserSync configuration
  • postcss.config.js — PostCSS plugin configuration

Step 2: Install Dependencies

Install all dependencies at the project root:

npm install

Step 3: Configure Per-Theme Build Scripts

Update the root package.json to include build and watch scripts for each theme. Each script must specify the correct paths to that theme's source CSS, output CSS, and Tailwind configuration file.

Example Multi-Theme package.json

The following example shows a root package.json with build and watch scripts for two themes (default and anvil). Each script specifies the full paths to source CSS, output CSS, and Tailwind configuration:

{
  "name": "magento-themes",
  "scripts": {
    "build-default": "npx tailwindcss --postcss -i app/design/frontend/Acme/default/web/tailwind/tailwind-source.css -o app/design/frontend/Acme/default/web/css/styles.css -c app/design/frontend/Acme/default/web/tailwind/tailwind.config.js --minify",
    "build-anvil": "npx tailwindcss --postcss -i app/design/frontend/Acme/anvil/web/tailwind/tailwind-source.css -o app/design/frontend/Acme/anvil/web/css/styles.css -c app/design/frontend/Acme/anvil/web/tailwind/tailwind.config.js --minify",
    "watch-default": "npx tailwindcss --postcss -i app/design/frontend/Acme/default/web/tailwind/tailwind-source.css -o app/design/frontend/Acme/default/web/css/styles.css -c app/design/frontend/Acme/default/web/tailwind/tailwind.config.js --watch --verbose",
    "watch-anvil": "npx tailwindcss --postcss -i app/design/frontend/Acme/anvil/web/tailwind/tailwind-source.css -o app/design/frontend/Acme/anvil/web/css/styles.css -c app/design/frontend/Acme/anvil/web/tailwind/tailwind.config.js --watch --verbose",
    "build-all": "npm run build-default && npm run build-anvil"
  }
}

Running Builds

After setup, run theme builds from the project root:

# Build a single theme
npm run build-default

# Watch a theme during development
npm run watch-anvil

# Build all themes
npm run build-all