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
classascls, 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,citeand 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#
- Installation: install and configure JSX
- First render: write a component
- From a view to progressive HTML: integrate a route and defer results
- Building a static site: render pages at build time
- Elements & attributes: JSX conventions