Skip to content
Vincle
Esc

Loading…

    Your views in JSX. Your app in HTML.

    Vincle lets you compose typed JSX views in your existing server. Start with one component, render it to HTML, and return it from a route.

    Compose a view#

    With @vincle/core, components are functions, props are TypeScript values, and the result is an HTML string. The renderer adds no browser runtime.

    import { renderToString } from "@vincle/core";
    
    function App({ name }: { name: string }) {
      return <h1>Hello, {name}!</h1>;
    }
    
    const page = <App name="world" />;
    const html = await renderToString(page);
    
    <h1>Hello, world!</h1>
    

    New to JSX? Coming from HTML templates maps what you write in Pug, EJS, Twig or Vue to it.

    Set up the package and JSX in TypeScript, then connect the rendered HTML to your server's response API. You keep your routing, data access, and deployment setup.

    Load data in your components#

    A component can be async. The renderer awaits its result before producing the final HTML.

    import { renderToString } from "@vincle/core";
    
    declare const db: {
      users: {
        findById(id: string): Promise<{ name: string; email: string }>;
      };
    };
    
    async function UserCard({ id }: { id: string }) {
      const user = await db.users.findById(id);
      return (
        <div class="card">
          <h2>{user.name}</h2>
          <p>{user.email}</p>
        </div>
      );
    }
    
    const html = await renderToString(<UserCard id="42" />);
    

    Async siblings start in document order and overlap as soon as one awaits; the output is joined in document order, and the string response waits for the whole tree.

    Let slower parts arrive later#

    Add @vincle/flow when a page should appear before all its data is ready. Wrap a slow component in Defer, provide a fallback, and use the streaming renderer to send the surrounding page before its deferred fragments. An adapter decides how fragments update the page: natively, or through HTMX or Turbo.

    import { renderToStream, Defer } from "@vincle/flow";
    import { NativeAdapter } from "@vincle/flow/adapters";
    
    const stream = renderToStream(
      () => (
        <html>
          <body>
            <h1>Page visible immediately</h1>
            <Defer target="comments" fallback={<p>Loading comments…</p>}>
              <Comments />
            </Defer>
          </body>
        </html>
      ),
      NativeAdapter,
    );
    // → ReadableStream<string>. Pipe it to the HTTP response.
    

    Follow a view from a route to streaming HTML.

    Add packages as you need them#

    Start with the core; each other package builds on it alone, so add one when its need shows up.

    Package What it adds Documented in
    @vincle/core Components rendered to an HTML string Guide
    @vincle/flow <Defer>: parts of a page that arrive later, streamed or as files Integration › Flow
    @vincle/ssg A static site generator: a directory of pages becomes HTML files Integration › SSG
    @vincle/precompile A build transform that turns JSX into template literals Integration › Precompile
    @vincle/eslint-plugin Lint rules for what escaping cannot judge, such as on* handlers README

    What the core gives you#

    You get an HTML string. Here's what makes that worth it:

    • TypeScript checks your templates. Props, attributes, CSS values — all typed. Misspell class as cls, and the compiler catches it before you run anything. See the Context & Scope API.

    • Security is the default, not a config. Every value is escaped for its context. Attributes that hold a URL (href, src, action, poster, cite and more) only accept safe schemes. raw() is the explicit opt-out — if HTML escapes you, it's one function call. See the security model.

    • The output works immediately. A complete HTML string you can send as a response, write to disk as a static site (static site generation, or SSG), or pass to an email provider. No transformation step. Email client compatibility is still your template design problem, not the renderer's.

    Vincle takes the place of a template engine, or of React's server renderer: components run on the server and produce HTML, and no JavaScript runtime reaches the browser. Add client-side behavior with the tools of your choice.

    Next steps#