Coming from HTML templates
If you can write HTML, you already have the landmarks of a Vincle view:
same tags, same attribute names (class, data-*, aria-*), same document
structure. What you add is JSX: markup written as a TypeScript expression,
with {…} where your data goes, checked by the compiler like any other
value. There is no separate template language to learn.
HTML, plus {…}#
A view is a function that returns markup. Familiar HTML is already valid JSX:
export function Greeting() {
return <h1>Hello, world!</h1>;
}
Each dynamic feature is one small step from there. A value goes in {…}:
export function Greeting({ name }: { name: string }) { return <h1>Hello, {name}!</h1>;}Called with name="world", it renders <h1>Hello, world!</h1>. An
attribute takes the same braces, with the names you know from HTML:
export function Link({ post }: { post: Post }) { return ( <a class="card" href={post.url}> {post.title} </a> );}A condition is an expression, a loop is map:
export function Posts({ user, posts }: PostsProps) { return ( <main> {user ? <p>Hello, {user.name}</p> : <a href="/login">Log in</a>} <ul> {posts.map((post) => ( <li>{post.title}</li> ))} </ul> </main> );}That is the whole bridge: write HTML, reach for {…} when something comes
from your data. The rest of this page translates the template constructs you
use today and lists the few places where JSX differs from HTML.
The same page, in the engine you know#
If you write Pug, EJS, Twig, Handlebars or Vue templates, you already think in HTML with holes in it. JSX is the same idea, minus the template language: the markup is not a string handed to an engine, it is an expression in your TypeScript code.
main
if user
p Hello, #{user.name}
else
a(href="/login") Log in
ul
each post in posts
li: a(href=post.url)= post.title
include footer.pug
div!= intro
<main>
<% if (user) { %>
<p>Hello, <%= user.name %></p>
<% } else { %>
<a href="/login">Log in</a>
<% } %>
<ul>
<% posts.forEach((post) => { %>
<li><a href="<%= post.url %>"><%= post.title %></a></li>
<% }) %>
</ul>
<%- include("footer") %>
<div><%- intro %></div>
</main>
<main>
{{#user}}<p>Hello, {{name}}</p>{{/user}}
{{^user}}<a href="/login">Log in</a>{{/user}}
<ul>
{{#posts}}
<li><a href="{{url}}">{{title}}</a></li>
{{/posts}}
</ul>
{{> footer}}
<div>{{{intro}}}</div>
</main>
<main>
{% if user %}
<p>Hello, {{ user.name }}</p>
{% else %}
<a href="/login">Log in</a>
{% endif %}
<ul>
{% for post in posts %}
<li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
{% include "footer.twig" %}
<div>{{ intro|raw }}</div>
</main>
<main>
<p v-if="user">Hello, {{ user.name }}</p>
<a v-else href="/login">Log in</a>
<ul>
<li v-for="post in posts"><a :href="post.url">{{ post.title }}</a></li>
</ul>
<Footer />
<div v-html="intro"></div>
</main>
In JSX, the template is a component: its data
arrives as props, the include is another component, a filter is a function
call ({name.toUpperCase()}), and trusted markup goes through raw():
import { raw } from "@vincle/core";import { Footer } from "./footer";export function Page({ user, posts, intro }: PageProps) { return ( <main> {user ? <p>Hello, {user.name}</p> : <a href="/login">Log in</a>} <ul> {posts.map((post) => ( <li> <a href={post.url}>{post.title}</a> </li> ))} </ul> <Footer /> <div>{raw(intro)}</div> </main> );}PageProps is the type of the data the template receives.
Where JSX differs from HTML#
The syntax is a superset of HTML, not HTML itself. A few differences come up early.
{…} takes an expression, not a statement#
An if statement does not fit inside {…}: use a ternary or && in the
markup, or compute the value before the return. false, null,
undefined and true render nothing; 0 renders 0, so write
{count > 0 && <Badge />}, not {count && <Badge />}.
An expression returns a single root#
Several siblings go in a fragment (<>…</>), and
every tag is closed (<br />, <input />) — the two habits JSX keeps from
XML.
Includes and layouts are components#
A component is a function whose name starts with a capital letter. Its
parameters are typed props: a missing or misspelled prop is a compile error,
not an empty string at render time. A layout takes the page through
children:
import type { JSX } from "@vincle/core";function Layout({ title, children }: { title: string; children: JSX.Element }) { return ( <html lang="en"> <head> <title>{title}</title> </head> <body>{children}</body> </html> );}const page = ( <Layout title="Blog"> <h1>Posts</h1> </Layout>);Escaping has one form#
Every {value} is escaped for where it lands, in text or in an attribute.
There is no pair of tags to choose between: trusted markup goes through
raw(), a function call you can search for. See the
security model.
The doctype is yours#
renderToString returns the markup you wrote: prepend <!DOCTYPE html> to a
full page yourself.
Setup#
JSX is compiled with your code: write .tsx files and add two lines to
tsconfig.json (TypeScript setup).
The same compiler gives your editor completion on every element's attributes.
What you give up#
A template compiled with your code cannot be loaded at runtime: markup stored in a database or edited by non-developers stays a job for a template engine.
Next steps#
- First render: your first component
- Elements & attributes: booleans,
style, void elements - Security model: what escaping covers