About
Philosophy
Build once. Move to any framework - without rewriting the product.
Migration is the product. Shared modules are the nucleus. An IR-first compiler is how you change frameworks. Seven modern web runtimes.
The problem
Teams lock into a stack early - Vue or React, Nuxt or Next - then pay a rewrite tax when the market, hiring, or a client demands another framework. Auth, i18n, theming, and API shape get copied into every project. Component-only toolchains leave the app, the routes, and the domain behind.
Nucleify treats migration between technologies as the durable layer of the monorepo - not a side experiment. Coverage is seven frameworks: Vue · React · Nuxt · Next · Astro · Svelte · Solid.
The vision
One nucleus. Three product surfaces. Seven frameworks. One migration pipeline.
- Shared modules - API, SQL, UI, and domain logic in
shared_modules/ - Three surfaces -
web/,admin/, anddocs/from the same nucleus - Migrate as a command - product convert for whole existing apps (no
*.nuc.tsxrewrite), optional portable emit for shared UI, import back from dirty emit - One Supabase backend - gateway-mediated, module-owned SQL
Day-to-day editing stays on Nuxt (web/). Switching frameworks is a compiler pass on your existing source - not a rewrite into Nucleify authoring format.
The nucleus metaphor
Like a cell nucleus, Nucleify coordinates the product. Each exported nuc_* module is a self-contained unit - frontend utils, optional API handlers, migrations, tests - that can be understood and tested independently.
- Self-contained modules - vertical slices, not scattered layers
- Clear boundaries - apps compose; modules do not import apps
- Organic growth - add or remove modules without rewiring the monorepo
- Collective strength - one domain model across web, admin, docs, and every framework host
Core principles
1. Any stack → any other
This is the core loop. Product convert moves an existing app - including an external folder or git URL via --path / --git - to another framework without rewriting into *.nuc.tsx (see Compiler). Optional portable *.nuc.tsx components emit through a custom IR when you want shared presentational UI. Emit edits import back to source. The business does not fork per host.
export PATH="$PWD/.config/bin:$PATH" # enables --target= / -t=
make web --target=next
make web -t=solid
make web --target=svelte
make web --target=astro
make admin --target=next
make admin -t=solid
make admin --target=svelte
# classic (no shim): make web TARGET=nextPublished CLI form (same convert):
nuc emit convert web --target=next
nuc emit convert admin --target=nextFramework choice becomes a build target, not an architectural fork.
2. Modules over monoliths
Domain logic lives in shared_modules/nuc_*, not duplicated across apps. See Feature-Sliced Design.
3. Gateway, not spaghetti
Privileged server access flows through web/src/server/api/[...slug].ts. Clients never hold service keys. Modules register handlers; the gateway dispatches.
4. Convention over configuration
Split Nuxt config, consistent module layout, Makefile shortcuts (make help), Husky-enforced checks - predictable paths reduce decision fatigue.
5. Overrides for forks, modules for sharing
White-label diffs use overrides/. Cross-product behavior belongs in shared_modules/.
6. Compiler honesty
Product convert is the migration path for existing apps. Portable authoring is optional and has explicit allowed/forbidden lists (compiler/PORTABLE.md). The IR bridges frameworks - we do not pretend Vue and React are identical. Round-trip import and product convert are first-class; a one-way component dump is not the goal.
Canonical Nuxt vs generated hosts
| Day-to-day (Nuxt) | Migrate / emit (convert) |
|---|---|
Edit Nuxt + Vue in web/ |
Next, Solid, Svelte, Astro product hosts + portable demos |
| Source of truth | Generated mirrors when a client or team needs another framework |
Converted hosts are not a second hand-maintained codebase. Fix the nucleus, re-run convert. Product messaging always lists all seven frameworks, even when daily editing stays on Nuxt.
Design system stance
UI primitives are framework-agnostic Lit components (nui-* from nucleify-ui). Tokens live in portable/nui/. Every host wraps the same custom elements - no duplicate button implementations per framework.
Quality bar
The monorepo enforces quality on pre-commit (pre-push is a no-op):
- Bash suite, Biome, TypeScript (web), Stylelint
- Nuxt production build
- Vitest (web + shared) and compiler tests / emit check
What Nucleify is not
- Not a meta-framework that hides hosts - the seven frameworks stay visible
- Not a component-only emit layer - product convert moves whole apps with shared modules
- Not a low-code builder - you write real TypeScript
- Not a hosted SaaS - you own Supabase and deployment
- Not “mystery modules” - six exported
nuc_*packages power the product today
Related docs
- Introduction - technical overview
- CLI -
nuc emitreference - Modules - module architecture
- Compiler - emit and convert
- Coding Standards - day-to-day conventions