Build one application and run it in the browser and Node.js.

Valyrian.js lets you build components, state, routing, data and forms in one application. The browser mounts or hydrates it, and Node.js imports the same application to render HTML for SSR.

Start in the browser, then run the same application in Node.js for SSR, hydrate it in the browser and add offline and PWA support as the app grows.

Valyrian.js is for teams that want explicit updates, JSX/TSX authoring, browser interactivity and server rendering without splitting the product into separate client and server apps.

Here, "isomorphic" means the same Valyrian application can run in both environments. Browser execution creates the interactive UI. Node.js execution renders HTML for responses.

• Quick Start
  • Browser (CDN)
  • Node (npm)
• Choose Your Path
• First 5 Minutes (Recommended)
• Official Learning Route
• Documentation
• Why Valyrian.js
• Testing Philosophy
• Tests
• More Guides
• Contributing
• Legal

Get a working screen first. Start with the CDN path to prove the mount-and-render path in the browser before expanding into Node tooling or SSR.

<script type="module">
  import "https://unpkg.com/valyrian.js";

  const { mount } = Valyrian;

  function App() {
    return "Hello from Valyrian.js";
  }

  mount("body", App);
</script>

Expected result: the text appears in the page body.

This snippet proves your first Valyrian screen can run in the browser. docs/2-getting-started.md starts from this same example, then expands it into richer components and local TSX/JSX tooling.

npm install valyrian.js

Then follow docs/2-getting-started.md for the inline build flow and the supported TSX setup (jsx: "react-jsx" + jsxImportSource: "valyrian.js").

When you are ready for SSR, Node.js can import the same application and render HTML for the browser to hydrate.

• Try it now (no install): use the CDN snippet above.
• Understand the same example in more detail: read docs/1-introduction.md, then continue with docs/2-getting-started.md.
• Build the official cumulative application: after Getting Started, follow docs/taskboard-tutorial.md.
• Add local TSX/JSX tooling in Node: continue with docs/2-getting-started.md (Node path and supported TSX setup).
• Run the same application in Node.js for SSR: complete chapters 1-3, then go to docs/7-full-stack-capability.md.

1. Copy the CDN snippet into an index.html file.
2. Open it in your browser and confirm the UI renders.
3. Read docs/1-introduction.md to see how the same application runs in the browser and Node.js.
4. Continue with docs/2-getting-started.md to expand the same example.
5. Continue with docs/taskboard-tutorial.md to build one application through interaction, routing, data, forms, SSR, hydration and offline/PWA behavior.

If this works, you have your first Valyrian screen running. The next steps grow the same app into routing, data, forms, SSR and offline support.

Taskboard is the official cumulative tutorial. It starts from the first browser render and extends the same application through seven observable stages:

1. Local TSX project.
2. Interaction with PulseStore.
3. Routing.
4. Async data with Request and Suspense.
5. Validated forms with FormStore.
6. Node.js SSR and browser hydration.
7. Offline queue, network status and service worker updates.

Each stage names the starting state, the applied change, the observable result and the next step. Start at docs/taskboard-tutorial.md.

• Start here: docs/toc.md
• Editorial style guide: docs/editorial-style-guide.md
• Introduction: docs/1-introduction.md
• Getting Started (No-Build First): docs/2-getting-started.md
• Taskboard Tutorial: docs/taskboard-tutorial.md
• The Essentials: docs/3-the-essentials.md
• Runtime core API reference: docs/3.1-runtime-core.md
• API Reference Standard: docs/api-reference-standard.md
• Building Single Page Applications (SPA Hub): docs/4-building-spa.md
• Advanced State Management (Hub): docs/5-advanced-state-management.md
• Run the Same Application in Browser and Node.js: docs/7-full-stack-capability.md
• Utilities and Ecosystem (Hub): docs/8-utilities-and-ecosystem.md
• Versioning and Compatibility Policy: docs/12-versioning-policy.md
• Website: https://valyrianjs.dev/

• One application runs in the browser and Node.js.
• The browser mounts or hydrates your app, and Node.js imports that same app to render HTML for SSR.
• Routing, data, forms, SSR, hydration and offline support grow from the same application.
• Built-in modules for routing, requests, state, forms, offline behavior and server-side rendering reduce the number of pieces you need to assemble for common app flows.
• Start with a simple browser screen, then use the same application in Node.js when you need SSR.
• The official Taskboard route demonstrates growth by accumulation instead of fragmented examples.
• Valyrian.js gives teams a compact app stack with explicit updates, JSX/TSX authoring, SSR, hydration and fewer pieces around the core UI.

Valyrian.js tests are behavior-first and API-contract driven. Public modules validate happy paths, edge cases, and documented consistency across browser-like and Node-like environments. Documentation examples are kept aligned with tested behavior.

bun test

For development mode in this repository:

bun run dev:test

• Recipes and integrations: docs/9-recipes-and-integrations.md
• Meta-framework CLI (downstream workflow): docs/10-meta-framework-cli.md
• Contribution guide: docs/11-contribution.md
• Versioning and compatibility policy: docs/12-versioning-policy.md

• Agent guidance: llms.txt
• Full documentation bundle for AI tools: llms-full.txt

• Run lint/format checks before opening a PR.
• Add or update tests for new behavior.
• Update docs in docs/ whenever public behavior changes.

Author: Masquerade Circus. License Apache-2.0