alveo

Opinionated React SSR framework built on Vite. Compiles components, renders pages server-side, and integrates with backend CMS projects.

Quick Start

npx alveo create my-app
cd my-app
bun install
bun run dev

CLI Commands

Command	Description
alveo dev	Start dev server with HMR, style watcher, and SSR
alveo build	Production build (static + SSR bundles)
alveo generate	Full pipeline: states, styles, build, prerender
alveo inte	Integration build for backend consumption
alveo styles	Compile SCSS stylesheets
alveo styles --watch	Watch and recompile SCSS on changes
alveo states	Aggregate component state JSON files
alveo create <name>	Scaffold a new project from the starter template

All commands accept --root <path> to specify the project root (defaults to cwd).

Project Structure

A consumer project looks like this:

my-app/
  src/
    assets/styles/       SCSS stylesheets (abstracts, functions, mixins, base)
    atoms/               Atomic design: smallest UI elements
    molecules/           Composed atoms
    organisms/           Composed molecules (each gets its own CSS)
    templates/           Page layout templates
    pages/               Page components (auto-discovered for routing)
    _helpers/            Utility components (RequireJs, RequireCss, ReactSection)
    _data/               Static data
    _api/                API client modules
    mocks/               MSW mock handlers
    client-components.tsx  Registry of client-rendered React components
  public/
    assets/images/       SVG sprites, icons
    assets/fonts/        Web fonts
    assets/vendors/      Third-party libraries
  index.html             HTML template
  vite.config.ts         Vite config (calls defineAlveoConfig)
  tsconfig.json          TypeScript config
  .env                   Environment variables

Configuration

vite.config.ts

import { defineAlveoConfig } from 'alveo';

export default defineAlveoConfig({
    root: import.meta.dirname,
});

.env

VITE_BASE_URL=/
VITE_PORT=15889
VITE_PATH_EXTENSION='.html'
VITE_TITLE_SUFFIX='My App'

# Integration paths (for alveo inte)
VITE_INTE_ASSET_DIR=../MyProject.Web/wwwroot/assets
VITE_INTE_PATTERN_DIR=../MyProject.Patterns

tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "skipLibCheck": true,
    "paths": {
      "@atoms/*": [
        "./src/atoms/*"
      ],
      "@molecules/*": [
        "./src/molecules/*"
      ],
      "@organisms/*": [
        "./src/organisms/*"
      ],
      "@templates/*": [
        "./src/templates/*"
      ],
      "@pages/*": [
        "./src/pages/*"
      ],
      "@helpers/*": [
        "./src/_helpers/*"
      ],
      "@data/*": [
        "./src/_data/*"
      ],
      "@mocks/*": [
        "./src/mocks/*"
      ]
    }
  }
}

Path Aliases

Alias	Resolves to
@atoms/*	src/atoms/*
@molecules/*	src/molecules/*
@organisms/*	src/organisms/*
@templates/*	src/templates/*
@pages/*	src/pages/*
@helpers/*	src/_helpers/*
@data/*	src/_data/*
@mocks/*	src/mocks/*
@alveo/*	alveo package internals

Client Components

Register React components for client-side hydration in src/client-components.tsx:

import { lazy } from 'react';

export const clientComponents = {
    header: lazy(() => import('./organisms/header')),
    people: lazy(() => import('./organisms/people')),
};

These render in the browser from <script data-rct="header"> tags in your HTML.

SCSS Conventions

• src/assets/styles/style-base.scss — main stylesheet entry point
• src/organisms/{name}/index.scss — per-organism styles, compiled to b-{name}.css
• src/templates/{name}/index.scss — per-template styles, compiled to p-{name}.css
• Abstracts, functions, and mixins barrels are auto-injected as @use preludes

Build Outputs

Command	Output
alveo build	dist/static/ (client), dist/server/entry-server.js (SSR)
alveo generate	Pre-rendered HTML pages in dist/static/pages/
alveo inte	Copies assets to VITE_INTE_ASSET_DIR, patterns to VITE_INTE_PATTERN_DIR
alveo styles	CSS files in public/assets/css/

Development

Setup

bun install

Build

bun run build

Test

bun run test
bun run test:coverage

Typecheck

bun run typecheck

Requirements

• Node.js >= 20 or Bun
• React 19
• TypeScript 5+

License

MIT