Skip to content
Vincle
Esc

Loading…

    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:

    greeting.tsx
    export function Greeting() {
      return <h1>Hello, world!</h1>;
    }
    

    Each dynamic feature is one small step from there. A value goes in {…}:

    greeting.tsx
    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:

    link.tsx
    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:

    posts.tsx
    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():

    page.tsx
    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:

    layout.tsx
    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#