Getting Started

Introduction

Build once. Move to any framework.

Nucleify is a modular full-stack monorepo. Keep your product in shared modules, develop day-to-day in Nuxt (web/), and migrate web, admin, or docs to another framework when you need to — without rewriting the business.

Shells: Vue · React · Nuxt · Next · Astro · Svelte · Solid — not a React/Next-only or Vue/Nuxt-only product.

Ship the nucleus once. Boot every shell.

What is Nucleify?

Nucleify is a pnpm workspace that bundles everything for a modern product:

Package	Path	Role
`@nucleify/web`	`web/`	Nuxt 4 landing app (Tryb A canonical)
`@nucleify/admin`	`admin/`	Nuxt 4 admin panel
`@nucleify/docs`	`docs/`	Astro 5 documentation site
`@nucleify/compiler`	`compiler/`	IR portable UI compiler
`@nucleify/shared-modules`	`shared_modules/`	Six exported feature modules

Supporting directories:

portable/nui/ — design tokens and Lit nui-* registration
overrides/ — per-package file overrides (overrides/{web,admin,docs,shared_modules}/)
supabase/ — DB config, migrations, edge functions
.config/ — Biome, Vitest, bash scripts

Dual-mode architecture: Tryb A & Tryb B

Mode	Stack	Command	Output
Tryb A (default)	Nuxt 4 + Vue 3.5	`make web`	`web/`
Tryb B (generated)	Next / Solid product shells	`make web TARGET=next` · `make web TARGET=solid`	gitignored emit tree (see Compiler)
Emit demos	Vue · React · Nuxt · Next · Solid	`make vue` · `react` · `nuxt` · `next` · `solid`	`{framework}/demo`

Tryb A is where you develop daily — pages, composables, and shared modules live in Vue. Tryb B and portable emit demos fan the same nucleus into other shells (Next, Solid, and framework demos including React/Vue/Nuxt). Astro hosts the docs site; Svelte and Solid are first-class emit/surface targets in product messaging and compiler work.

All paths share shared_modules/, Supabase, and design tokens. You do not maintain seven unrelated codebases.

The compiler

The compiler (@nucleify/compiler) is how you migrate UI across shells. It works at two levels:

1. Portable components (`*.nuc.tsx`)

Author framework-agnostic UI with #nuc-compiler/runtime. The compiler emits sibling .vue, .tsx, and .css files:

import { component, state, handler } from '#nuc-compiler/runtime'

export default component({
  name: 'Counter',
  props: { label: { type: 'string', default: 'Count' } },
  setup(props) {
    const count = state(0)
    const onInc = handler(() => count.set(count.value + 1))
    return () => (
      <button type="button" onClick={onInc}>
        {props.label}: {count.value}
      </button>
    )
  },
})

See Compiler and compiler/PORTABLE.md for the full authoring rules.

2. Product shell conversion

Convert an entire Nuxt app to Next or Solid:

make web TARGET=next    # → web-next/
make web TARGET=solid   # → web-solid/

Same routes, shared modules, different framework shell. Output is generated by the compiler — not part of the canonical monorepo layout.

Shared modules

Six exported feature modules live in shared_modules/:

Module	Domain
`nuc_api`	API client, gateway dispatch, auth forms, entity requests
`nuc_colors`	Theme/color system, SCSS variables
`nuc_dark_mode`	Dark mode preference
`nuc_globals`	Media queries, global styles, shared types
`nuc_languages`	i18n, locale messages, translations API
`nuc_stores`	Pinia/Zustand helpers, cookie/localStorage utils

Apps import modules directly or via the modules alias (configured in web/.config/nuxt/structure.ts). Registration for the web app happens in web/src/plugins/modules.ts.

Read more: Modules · Feature-Sliced Design

API gateway

All server API traffic flows through one Nitro catch-all:

web/src/server/api/[...slug].ts
  → dispatchSupabaseApiGateway()
  → shared_modules/nuc_*/supabase/api/handle.ts

Module handlers register in shared_modules/nuc_api/supabase/api/gateway_dispatch.ts. Client code calls /api/... — never Supabase directly from the browser for privileged operations.

Design system

UI primitives are Lit web components from nucleify-ui (nui-button, nui-icon, …). Design tokens and registration live in portable/nui/. Every shell consumes the same custom elements; the compiler maps nui-* tags in *.nuc.tsx across emit targets (Vue, React, Solid, and sibling shells).

Monorepo layout

nucleify/
├── web/                    # @nucleify/web — Nuxt 4 landing (Tryb A)
│   ├── nuxt.config.ts
│   ├── .config/nuxt/       # split Nuxt config
│   └── src/
│       ├── pages/          # Vue pages (e.g. home/sections/)
│       ├── plugins/        # modules.ts, nucleify-ui.client.ts
│       ├── composables/
│       ├── layouts/
│       └── server/api/     # Nitro API gateway [...slug].ts
├── admin/                  # @nucleify/admin — Nuxt 4 admin
├── docs/                   # @nucleify/docs — Astro 5 docs
├── compiler/               # @nucleify/compiler — IR portable UI compiler
├── shared_modules/         # six exported nuc_* modules
├── portable/nui/           # design tokens, Lit nui-* registration
├── overrides/              # overrides/{web,admin,docs,shared_modules}/
├── supabase/
├── .config/
├── Makefile
└── package.json

Full breakdown: Monorepo Layout

Quick commands

Command	What it does
`make run`	Create `.env`, install deps, husky, sync rules, build compiler
`make web`	Start Nuxt dev server (`web/`)
`make web TARGET=next`	Convert Vue shell to Next, start dev (generated output)
`make web TARGET=solid`	Convert Vue shell to Solid, start dev (generated output)
`make vue` / `react` / `nuxt` / `next` / `solid`	Portable emit demos
`make admin`	Start admin Nuxt dev
`make docs`	Start Astro docs dev
`make compiler`	Run `pnpm compiler:check` + `pnpm compiler:build`

Equivalent pnpm shortcuts: pnpm dev, pnpm admin, pnpm docs.

Next steps

Installation — prerequisites and first setup
Quick Start — run the landing app in minutes
Monorepo Layout — where everything lives
Environment — configure Supabase and app vars