Nucleify Docs

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.

  1. Shared modules - API, SQL, UI, and domain logic in shared_modules/
  2. Three surfaces - web/, admin/, and docs/ from the same nucleus
  3. Migrate as a command - product convert for whole existing apps (no *.nuc.tsx rewrite), optional portable emit for shared UI, import back from dirty emit
  4. 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=next

Published CLI form (same convert):

nuc emit convert web --target=next
nuc emit convert admin --target=next

Framework 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