DOCSEARCHbyAlgolia
Submit Docs

spartan

repository·main·Indexed 25 days ago

https://github.com/spartan-ng/spartan

A suite of tools for Angular full-stack development featuring spartan/ui for accessible, un-styled UI primitives and spartan/stack for an opinionated full-stack setup built on AnalogJs. It includes the @spartan-ng/brain package providing headless Angular primitives for keyboard navigation, focus management, and ARIA wiring, as well as the @spartan-ng/cli for automated installation and styling.

Tokens
78.7K
Snippets
125
Records
603
Agent score
78%

What's inside spartan

  1. Overview of spartan

    main

    spartan provides cutting-edge tools for Angular full-stack development. It features spartan/ui, a collection of accessible, un-styled UI primitives for Angular that uses a copy-paste, shadcn-style approach for styling (helm styles). It also includes spartan/stack, an opinionated full-stack setup built on AnalogJs.

    Key components include:

    • spartan/ui: Accessible UI primitives.
    • spartan/stack: Full-stack setup based on AnalogJs.

  2. Use @spartan-ng/brain/overlay for floating panels

    main
    The @spartan-ng/brain/overlay package provides a floating panel primitive designed for non-dialog portal components. Use this when you need to render UI elements that should float over the main content via a portal but do not follow the strict interaction patterns of a modal dialog.

  3. Understand cli-smoke test coverage

    main

    The cli-smoke suite covers several workspace and styling configurations to ensure the CLI works across different environments:

    • Workspace Types:
      • nx: Monorepo configurations (both library and entrypoint types, and both buildable and non-buildable).
      • nx-standalone: Single-app Nx workspace without a tsconfig.base.json.
      • acli: Standard Angular CLI (no Nx).
      • all-components: Generates every supported primitive into an Angular CLI app (the slowest test cell).
    • Styling Coverage:
      • style-acli-<style> and style-nx-<style>: Exercises specific registry styles (nova, maia, luma, lyra, mira, and the default vega) to ensure the CLI correctly replaces spartan-* placeholders with the appropriate registry classes.

  4. Understand the spartan/ui architecture

    main

    spartan/ui is an Angular UI library built on a two-layer architecture:

    1. Brain (@spartan-ng/brain): An accessible, unstyled layer of headless primitives (directives/components) installed via npm. This layer handles behavior and accessibility.
    2. Helm (@spartan-ng/helm): The styled layer using Tailwind CSS and class-variance-authority. Unlike Brain, Helm code is copied directly into your project by the CLI, allowing you to own, customize, and style the components locally.

    Usage Pattern: You compose Helm directives/components onto host elements. Helm automatically wires up the corresponding Brain primitive under the hood. Always prefer using existing Helm components over writing custom markup.

  5. Understand the Spartan two-layer model

    main

    Spartan/ui uses a two-layer architecture to separate logic from styling:

    1. Brain Primitives: These are real npm packages (@spartan-ng/brain/<name>) installed into your node_modules. You should not edit these directly. Updates are handled via npm and healthcheck migrations.
    2. Helm Styled Components: These are components copied directly into your project (at the location specified by componentsPath) by the CLI. You own this code and are encouraged to customize it freely.

  6. Quickstart setup with spartan CLI

    main

    For the easiest setup, use the @spartan-ng/cli. It automates the installation of secondary entry points and copies matching helm styles into your codebase. Run the following commands to initialize the project and add UI components:

    npm install -D @spartan-ng/cli
ng g @spartan-ng/cli:init
ng g @spartan-ng/cli:ui

  7. Set up the spartan stack example app

    main

    The spartan stack example uses Supabase, Drizzle, Analog, tRPC, Tailwind, Angular, and Nx.

    Prerequisites

    • pnpm package manager
    • Node.js (version 20.17.0 is verified)
    • A Supabase account

    Database Configuration

    1. Create an .env file at the root of your Nx workspace.
    2. Add your Supabase connection string:
    DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-SUPABASE-REFERENCE-ID].supabase.co:5432/postgres?schema=public"
    1. Run the following SQL in your Supabase editor to initialize the required tables:
    create table
  public.note (
    id bigserial,
    title text not null,
    content text null,
    created_at timestamp with time zone null default current_timestamp,
    constraint notes_pkey primary key (id)
  ) tablespace pg_default;

    Run the Development Server

    Start the application with:

    pnpm nx serve app

    or

    pnpm run dev

    Navigate to http://localhost:4200/ to view the app.

    pnpm nx serve app