Getting Started

FrontAlign is a next-generation UI Engine for the modern web.

It is not just a CSS framework or a component library. FrontAlign combines a design-token driven CSS foundation, utility-first layout system, theme-aware styling, intelligent JavaScript runtime, and framework-agnostic component APIs into one cohesive engine for building scalable interfaces.

The core idea is simple:

Static interfaces should remain CSS-first. Interactive interfaces should initialize intelligently. Dynamic interfaces should stay predictable, lightweight, and easy to maintain.

FrontAlign works in plain HTML, CDN environments, and modern frameworks such as React, Next.js, Vue, and Astro — while keeping the same class system, component behavior, runtime model, and developer experience.

Install the package

Choose the setup that fits your project. FrontAlign can be installed from NPM for application workflows or loaded directly from a CDN for browser-first projects.

npm install frontalign

Import the CSS

The CSS bundle contains the visual foundation: design tokens, base styles, layout utilities, component styles, responsive helpers, and dark mode variables.

import "frontalign/css";

Use the CSS bundle when you only need the visual system. Add the JavaScript runtime when your page uses interactive components.

Initialize the runtime

Initialize the FrontAlign runtime once on the client.

import { FrontAlign } from "frontalign";

const fa = new FrontAlign();

Calling new FrontAlign() activates the runtime layer. It registers delegated components, observes lazy components, handles lazy images, watches dynamic DOM changes, and prevents duplicate initialization internally.

Choose Your Workflow

FrontAlign supports two primary workflows. Use the one that matches how your project is built.

CDN configuration is passed directly to the runtime. NPM configuration is handled through fa.config.js and processed by the Compiler & JIT Engine.

Architecture Layers

FrontAlign is built around three complementary systems.

This page gives you the setup path. The deeper implementation details live in the dedicated Architecture and Compiler Engine guides.

Use Interactive Components

For CDN projects, the instance API is the most convenient way to create or control components from JavaScript.

<script>
  const fa = new FrontAlign();

  fa.carousel.create("#hero-carousel", { loop: true });
  fa.modal.alert({
    heading: "Welcome",
    content: "FrontAlign is ready.",
  });
  fa.toast.show({
    message: "Saved successfully.",
    status: "success",
  });
</script>

For NPM projects, you can still use the instance API, but direct imports are usually cleaner when you only need specific components.

import { Toast, Carousel } from "frontalign";

Toast.show({
  message: "Saved successfully.",
  status: "success",
});

const carousel = Carousel.create("#hero-carousel", { loop: true });

For React and Next.js projects, use the React Integration guide instead of manually wiring runtime behavior inside every component.

CDN Configuration

CDN projects do not use fa.config.js. Pass runtime configuration directly when creating the FrontAlign instance.

<script src="https://cdn.jsdelivr.net/npm/frontalign/dist/js/frontalign.min.js"></script>

<script>
  const fa = new FrontAlign({
    theme: {
      primary: "#2563eb",
    },
  });
</script>

Use this setup when you want FrontAlign to run directly in the browser without a build pipeline.

NPM Configuration

For NPM projects, define your project-level design layer in fa.config.js.

my-project/
├─ app/
├─ public/
├─ package.json
└─ fa.config.js

export default {
  theme: {
    primary: "#2563eb",
    font: "Inter, sans-serif",
    extend: {
      brandSurface: "#f8fafc",
      cardRadius: "1rem",
    },
  },
  fonts: [
    {
      family: "Inter",
      weights: "400;500;600;700",
      alias: "inter",
      category: "sans-serif",
    },
  ],
  classes: {
    "brand-card": {
      "background-color": "var(--brand-surface)",
      "border-radius": "var(--card-radius)",
      padding: "var(--space-lg)",
      dark: {
        "background-color": "#111827",
      },
    },
  },
};

Then run the CLI.

npx frontalign dev

Use dev while working locally. Use build before production so FrontAlign can generate optimized project output.

For scan targets, theme tokens, fonts, custom classes, safelists, caching, and production output details, continue with the Compiler Engine guide.

Framework Integrations

FrontAlign is framework-agnostic. You can use it with plain HTML, static sites, React, Next.js, Vue, Astro, or any environment that can load CSS and browser JavaScript.

For React and Next.js applications, use the dedicated integration layer.

import { useNavbar, useModal } from "frontalign/react";

export default function App() {
  useNavbar();
  useModal();
  return <div>...</div>;
}

Continue with the React Integration guide for provider setup, hooks, component APIs, and Next.js usage.

Recommended Next Steps