Advanced Installation

The standard installation method for Maple is a drop-in <script> tag served from a CDN, as shown in the Quick Start. This page covers two advanced setups: serving the runtime script from your own origin instead of a CDN, and using the module build for deeper integration and custom tooling.

Both approaches start with installing the package via npm (or your preferred package manager):

npm install @f12io/maple

Self-Hosting the Runtime

The npm package ships the exact runtime script that the CDN serves, at @f12io/maple/dist/maple.js. Instead of pointing at a CDN, you can copy this file out of node_modules into your build output and include it as a first-party script. Your Maple version is then locked by your lockfile and upgraded through your normal dependency workflow, and your pages make no third-party requests — useful for strict Content Security Policies, offline development, and air-gapped deployments.

index.html


<head>
  <script src="/vendor/maple.js"></script>
</head>

Keep the Script Blocking

Self-hosting does not change the loading rules: Maple must still be a blocking script in the document <head>, for the same reason your stylesheet is — styles have to exist before the browser paints. async, defer, type="module", and end-of-body placement all defeat that. Some framework lint rules (such as Next.js no-sync-scripts) flag blocking scripts. For Maple this is intentional, so suppress the rule for this one line.

The only framework-specific part is copying the file into your static output. The sections below show common setups.

Angular

Add an asset entry to angular.json so the CLI copies the script from node_modules into the build output root:

angular.json


"assets": [
  {
    "glob": "maple.js",
    "input": "node_modules/@f12io/maple/dist",
    "output": "/"
  }
]

Then reference it from the document head — this very documentation site is installed the same way:

src/index.html


<head>
  <script src="maple.js"></script>
</head>

React and Vue (Vite)

For Vite-based apps — including the standard React, Vue, and Svelte templates — the simplest option is to copy maple.js into the public/ directory. To keep the served file in sync with the installed package automatically, use vite-plugin-static-copy:

npm install --save-dev vite-plugin-static-copy

vite.config.js


import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/@f12io/maple/dist/maple.js',
          dest: 'vendor',
        },
      ],
    }),
  ],
});

Then include the script in the document head of your index.html:

index.html


<head>
  <script src="/vendor/maple.js"></script>
</head>

Next.js

Next.js serves static files from the public/ directory. Copy the script there after every install so it stays in sync with the installed version:

package.json


{
  "scripts": {
    "postinstall": "cp node_modules/@f12io/maple/dist/maple.js public/maple.js"
  }
}

Then add a plain, blocking script tag to the head of your root layout. Avoid next/script here — none of its loading strategies produce a synchronous blocking script:

app/layout.tsx


export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts */}
        <script src="/maple.js" />
      </head>
      <body>{children}</body>
    </html>
  );
}

Animations: Self-Host keyframes.css Too

If you use Maple's animation utilities, the companion stylesheet at @f12io/maple/dist/keyframes.css can be self-hosted the same way — for example by adding it to the styles array in angular.json, importing it from your bundle entry point, or copying it alongside maple.js.

Using the Module Build

For applications that bundle everything — and for custom tooling built on top of Maple — you can import the engine from @f12io/maple instead of loading the runtime script, and start it yourself:

main.ts


import { startRuntime } from '@f12io/maple';

const stopMaple = startRuntime();

// Later, if your app owns the lifecycle:
stopMaple?.();

startRuntime returns a teardown function that stops the engine, or undefined in non-browser environments (such as during server-side rendering) where there is no document to observe. Note that application bundles usually execute after the first paint, so for content-first pages the blocking runtime script remains the recommended setup; the module build is best suited to client-rendered SPAs and tooling.

Exposed APIs

The module build of Maple (@f12io/maple) exposes several core functions and constants, allowing for deeper integration, custom runtime initialization, or custom tooling. The following APIs are exported:

Core Functions

startRuntime: Initializes the Maple CSS engine runtime and returns a teardown function (or undefined outside the browser).
parseClass: Parses a raw Maple utility class string into its constituent parts (media query, selector, property, value, etc.).
buildRule: Generates complete CSS rule data (RuleData) from a raw utility class string.
convert: Converts a raw class string into a CSS string, handling alias expansion and automatically inserting the generated rules into the active stylesheet.

Helper Namespaces

StringHelper: String utilities used throughout the engine — case conversion (kebab/camel), splitting, bracket removal, and variable escaping.
PropertyHelper: Utilities for resolving CSS properties and classifying values — checking known properties, number/angle/color values, reserved keywords, timing functions, and animation keywords.

Types and Constants

Configuration Constants: Various default settings and configurations (core/constants/config).
Dictionaries: Standard Maple terminology, keywords, and CSS mappings (core/constants/dictionaries).
Regex Patterns: Patterns for safely parsing classes and tokens (core/constants/regex).
Units: Standard unit arrays and mappings (core/constants/units).
Types: TypeScript interfaces and types for the internal structure, parsing logic, and configuration.

Precalculated Maps

PRECALCULATED_PROP_ABBREVIATIONS: A dictionary of shorthand property abbreviations used in Maple mapped to their full CSS properties.
PRECALCULATED_PROP_TYPES: A dictionary that maps CSS properties to their expected serialization strategies and value constraints.