Table of Contents & Menu
On this page
Navigation

Centralized NPM Dependencies for Multi-Theme Projects

Learn to manage a single Node.js/NPM installation at your Magento project root for building multiple Hyvä themes. This centralizes build dependencies, similar to Luma/Frontools workflows, avoiding duplication across themes.

Advanced Configuration

This setup requires advanced knowledge of Node.js package management, Tailwind CSS content configuration, and multi-theme build workflows. Support is provided for bugs only, not configuration assistance.

When to Use This Approach

Centralize NPM dependencies for multiple Hyvä themes sharing build tooling. For simpler needs like sharing CSS variables or utility classes, see the Shared CSS documentation.

Using System-Wide Global Packages

Some tools, like BrowserSync, are suitable for global installation. This makes them available across all projects on your machine, ideal for frequently used CLI tools.

Installing BrowserSync Globally

To install BrowserSync 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

Centralize all NPM dependencies at the Magento project root. This allows managing build tooling for multiple themes from a single location, similar to Luma/Frontools workflows.

Alternative: Wrapper Scripts

Alternatively, use bash or PHP wrapper scripts to run npm run build within each theme. This keeps dependencies isolated per-theme but offers a single build entry point.

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 these 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 dependencies at the project root:

npm install

Step 3: Configure Per-Theme Build Scripts

Update the root package.json with build and watch scripts for each theme. Ensure each script specifies the correct paths for source CSS, output CSS, and Tailwind configuration.

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

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