Installation

1. Initialize Fasla, once per project. This writes components.json, which every add reads:

npx @smicolon/fasla-ui@latest init

Set up with @smicolon/cli? If it was 0.4 or later, keep going with this command in the same project. Nothing needs re-running. If it was 0.3 or earlier, run npx @smicolon/fasla-ui@latest init once first. It repairs the project’s components.json, which the shadcn CLI can’t read until then, and moves the files those versions put in the wrong folder.

init also writes the cn helper and installs the two packages it imports with your project’s package manager. If that install fails, init prints the command to run, which is one of these:

npm install clsx tailwind-merge

On Tailwind 3, the command installs tailwind-merge@^2, as tailwind-merge 3 supports only Tailwind 4. init and add also replace a tailwind-merge that is, or could become, 3:

npm install clsx tailwind-merge@^2

2. Add a component:

npx @smicolon/fasla-ui@latest add button

Or add several at once:

npx @smicolon/fasla-ui@latest add card input badge

add then installs the packages the components import, with your project’s package manager, and skips any your project already has at a compatible version. If that install fails, add keeps the files it wrote and prints the command to run. To print the command instead of installing, add --no-install.

List everything the registry offers:

npx @smicolon/fasla-ui@latest list

Without questions: for agents and CI

init asks questions only when a terminal is there to answer them. Run without one, as an agent or a CI job does, it never waits: pass --yes to accept every default, or pass all three of --path, --style and --theme. When a choice is missing, init lists the flags to pass, writes nothing and exits with an error.

• --yes (-y) accepts every default and asks nothing.
• --path is the folder components go in, such as src/components. The CLI puts them in a ui folder under it, so src/components/ui gives the same result.
• --style is the shadcn style written to components.json: default or new-york.
• --theme is the theme layer: fasla for Fasla’s colours, or brand to keep yours.
• --no-install prints the install commands instead of running them.

For example:

npx @smicolon/fasla-ui@latest init --yes
npx @smicolon/fasla-ui@latest init --path src/components --style default --theme fasla
npx @smicolon/fasla-ui@latest add button --yes

When it finishes, init lists each file it created or changed and the command to run next. add also needs --yes when there is no terminal.

Starting from scratch: use Fasla’s colours. Fasla’s light and dark palette, its radius and the Geist font, on top of the base layer:

npx shadcn@latest add https://fasla.smicolon.com/r/theme.json https://fasla.smicolon.com/r/font-geist.json

On Next.js 14, set the project up with npx @smicolon/fasla-ui@latest init, not shadcn init: shadcn’s setup writes Tailwind 4 styles and loads Geist from next/font, and Next.js 14 has neither, so the build fails. Then leave out font-geist.json, as the Next.js 14 template already loads Geist:

npx shadcn@latest add https://fasla.smicolon.com/r/theme.json

I have a brand: keep my colours. The base layer only: the tokens shadcn doesn’t have (success, warning, info and the soft tints), the type scale with Arabic line heights, the Arabic setting and the Cairo font. It changes no colour you already have:

npx shadcn@latest add https://fasla.smicolon.com/r/theme-base.json

1. Install dependencies:

npm install class-variance-authority clsx tailwind-merge framer-motion

On Tailwind 3, install tailwind-merge@^2 instead. tailwind-merge 3 supports only Tailwind 4, and on Tailwind 3 it drops classes it doesn’t know, such as outline:

npm install class-variance-authority clsx tailwind-merge@^2 framer-motion

2. Add the cn utility to your project:

// lib/utils.ts
import { type ClassValue, clsx } from "clsx"
import { extendTailwindMerge } from "tailwind-merge"

const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["xxs", "link", "list-header"] }] } },
})

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

3. Copy each component from its file in the registry, such as https://fasla.smicolon.com/r/button.json for Button. https://fasla.smicolon.com/r/registry.json lists them all.

In each file, files holds the source in content and the path to save it at in target. dependencies lists the packages to install, and registryDependencies the other Fasla components it needs, which you copy the same way.