Theme Registry Webpack Plugin

Scanning certain directory for templates and autogenerate theme registry file for each found theme.
For more information please check @4i4/theme-registry.

Why this package exists?

When working with multiple themes and templates you need to manually add/remove the templates from your registries.
This plugin automatically doing that for you and keep everything in check.

Installing:

Using npm:

$ npm install @4i4/theme-registry-webpack-plugin

Using yarn:

$ yarn add @4i4/theme-registry-webpack-plugin

Using pnpm:

$ pnpm add @4i4/theme-registry-webpack-plugin

Usage:

Webpack config

const ThemeRegistryPlugin = require("@4i4/theme-registry-webpack-plugin");

const options = {};

module.exports = {
  plugins: [new ThemeRegistryPlugin(options)]
};

Options

| Option | Type | Default value | Description | |-------------|-----------|-------------------|---------------------------------------------------------------------------| | themesDir | string | ./src/themes | The directory that contains all themes | | templates | string | ./templates | The directory that contains all templates for each theme | | isNextJS | boolean | false | If set to true then next/dynamic will be used instead of React.lazy |

Requirement:

For each theme you need to create a configuration file in the root of the theme. The plugin looks for theme.ts, then theme.js, and finally theme.json. Each file supports the following properties:

| Option | Type | Required | Description | |------------|------------|--------------|-------------------------------------------------------------------------------------------------------| | parent | string | No | The name of the parent theme. | | context | string[] | No | Array of context to be used. In no context is set, then all templates will be set to the default one. | | settings | object | No | Map of registry settings entries that will be registered under the _settings scope. Values can be inline objects or relative module paths. |

Note: loading a theme.ts file requires ts-node to be available in your build environment.

TypeScript projects can import the helper types from @4i4/theme-registry-webpack-plugin/types/theme-config to annotate their theme configuration (for example in theme.ts):

import type { ThemeConfig } from "@4i4/theme-registry-webpack-plugin/types/theme-config";

const config: ThemeConfig = {
  context: ["layout"],
  settings: {
    palette: "./settings/palette.json",
    typography: {
      headingFont: "Inter",
      bodyFont: "Inter"
    }
  }
};

Working with theme settings

When theme.json provides a settings object, each key/value pair is injected into the generated registry under the reserved _settings scope introduced in @4i4/theme-registry.

{
  "context": ["layout"],
  "settings": {
    "palette": "./settings/palette.json",
    "typography": {
      "headingFont": "Inter",
      "bodyFont": "Inter"
    }
  }
}

• String values are treated as module paths relative to the theme root (prefix with ./ when needed). The plugin will import the file and assign the exported value to _settings.
• Plain objects (or arrays) are embedded directly in the generated registry.

The generated registry contains entries similar to:

import settingsPalette from "./settings/palette.json";

// Settings
registry.set("palette", settingsPalette, "_settings");
registry.set("typography", { "headingFont": "Inter", "bodyFont": "Inter" }, "_settings");

Default folder structure:

.
├── ...
├── src
│   └── themes                  # The directory that contains all themes
│       ├── theme_1             # Theme 1
│       │   ├── theme.json      # Theme 1 config file
│       │   └── templates       # The directory that contains all templates
│       │       ├── layout      # Context directory
│       │       ├── icons       # Context directory
│       │       └── grid        # Context directory
│       │
│       └── theme_2             # Theme 2
│           ├── theme.json      # Theme 2 config file
│           └── templates       # The directory that contains all templates
│               └── layout      # Context directory
└── ...

Theme inheritance:

if parent is set in the theme.json the theme registry of the parent will be inherited.

The plugin prefers a theme sibling directory matching the parent name. If no directory is found, it will try to import the registry from a package with the same name (first <parent>/registry, then <parent>).

Example

Structure:

.
├── themes
│   ├── theme_1
│   │   └── theme.json
│   └── theme_2
│       └── theme.json

./themes/theme_2/theme.json

{
  "parent": "theme_1"
}

That will generate the following registry:

import parent from "../theme_1/registry";
const registry = parent.clone();
...
export default registry;

Using the context:

By default, all templates will be assigned to the default context.
If you want certain context directory to be used then you need to set it in the theme.json

Example

Structure:

.
├── themes
│   ├── theme_1
│   │   ├── theme.json
│   │   ├── layout
│   │   │   └── page.tsx
│   │   ├── grid
│   │   │   ├── grid.tsx
│   │   │   └── container.tsx
│   │   └── icons
│   │       ├── icon_1.tsx
│   │       └── icon_2.tsx

./themes/theme_1/theme.json

{
  "context": ["icons"]
}

That will generate the following registry:

import Registry from "@4i4/registry";
import { lazy } from "react";
const registry = new Registry();

// Layout
registry.set("page", lazy(import("./templates/layout/page")));

// Grid
registry.set("grid", lazy(import("./templates/grid/grid")));
registry.set("container", lazy(import("./templates/grid/container")));

// Icons
registry.set("icon_1", lazy(import("./templates/icons/icon_1")), "icons");
registry.set("icon_2", lazy(import("./templates/icons/icon_2")), "icons");

export default registry;