adonisjsx v0.3.0

Features

• JSX as a runtime, usable everywhere in your app
• Config for global layouts
• Extended HTTPContext with jsx rendering and streaming methods
• Uses @kitajs/html for JSX runtime

First steps

# Install the package
npm i adonisjsx
# Register providers and config
node ace configure adonisjsx

Add jsx factories

After installing package, extend your tsconfig.json compiler options:

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "Html.createElement",
    "jsxFragmentFactory": "Html.Fragment"
  },
  // Optionally add the ts-html-plugin for xss protection
  // the package is installed automatically if you are using adonisjsx
  "plugins": [{ "name": "@kitajs/ts-html-plugin" }]
}

Register jsx runtime

As in jsxFactory and jsxFragmentFactory, Html class must be available in scope whenever you are using JSX. You can import it directly in your files when using JSX:

import { Html } from 'adonisjsx'

router.get('/', async ({ view }) => {
  return <div>Hello World</div>
})

Or add it globally by registering Html module. Add an import to your server.ts at the top of the file:

import 'adonisjsx/register'

Update useAsyncLocalStorage

You should also update your app.ts useAsyncLocalStorage to true if you want to access helpers that depend on HttpContext to work.

API

With the JSX configured, whenever you use it will be compiled to string, so you can simply return JSX from your routes, controllers, or any other place in your app. However, it may get tedious if you are accustomed to using layouts or you want to use more powerful features like streaming. The package gives you a few tools to make your life easier.

HttpContext.jsx

jsx: <
  TData extends Record<string, unknown>,
  TOptions extends {
    layout?: Component
    data: TData
  },
>(
  view: Component<TData> | string,
  options?: TOptions
) => Promise<JSX.Element>

You can render your components with the jsx util. It will wrap your component with global layout by default (which you can override through options or change it globally in the jsx.ts config published by the package).

// routes.tsx
import { MyComponent, Layout } from '#components'
route.get('/', async ({ jsx }) => {
  return jsx(MyComponent)
  // If your component takes props, data option will be typed accordingly
  return jsx(MyComponent, { data: { name: 'John' }, layout: Layout })
})

HttpContext.streamJsx

streamJsx: <TData extends Record<string, unknown>, TOptions extends {
    layout?: Component;
    errorCallback?: (error: NodeJS.ErrnoException) => [string, number?];
    data: TData;
}>(view: Component<TData & {
    rid?: number | string;
}>, options?: TOptions) => void

You can await any data in the component normally, as they are not react components but just functions that are converted from syntax sugar into pure javascript.

async function MyComponent() {
  const data = await fetch('https://api.com/data')
  return <div>{data}</div>
}

But you may want to show most of your UI instantly, and then stream only the parts that require async data. You can do that with streamJsx method. It will render the component and then stream the async parts as they resolve. Underneath, this method uses AdonisJS streaming, so you do not return the result of the method, you just call it.

streamJsx takes the same options as jsx method, but also accepts errorCallback option, which is called when an error occurs during streaming. By default, it will log the error and send 500 status code, but you can override it to handle errors in your own way. It comes directly from the framework streaming methods. The method will also pass the render id to your component - through rid prop that you can pass to the Suspense component as unique identifier. If you want to, feel free to generate one yourself.

import { Suspense } from 'adonisjsx'

router.get('/', async ({ streamJsx }) => {
  streamJsx(MyComponent, { errorCallback: (error) => ([`Rendering failed: ${error.message}`, 500]) })
})

function MyComponent({ rid }) {
  return (<>
    <div>Instant UI</div>
    <Suspense
      rid={rid}
      fallback={<div>Loading username...</div>}
      catch={(err) => <div>Error: {err.stack}</div>}
    >
      <MyAsyncComponent />
    </Suspense>
  </>)
}

async function MyAsyncComponent() {
  const data = await fetch('https://api.com/data')
  return <div>{data}</div>
}

viteAssets

function viteAssets(entries: string[], attributes: Record<string, unknown> = {}): JSX.Element

If you use vite with AdonisJS, there are helper methods for edge templates that integrate your templates with vite. adonisjsx provides similar helpers for JSX.

You can use viteAssets method to generate resource tags in your JSX that refer to the vite entries.

For vite config like this:

adonisjs({
  entrypoints: ['resources/js/app.js'],
})

You can add the javascript entry to your JSX like this:

import { viteAssets } from 'adonisjsx'

function MyComponent() {
  return (
    <html>
      <head>
        {viteAssets(['resources/js/app.js'])}
      </head>
      <body>
        <div>Hello World</div>
      </body>
    </html>
  )
}

viteReactRefresh

function viteReactRefresh(): JSX.Element

This function will add the necessary script tags to enable vite's react refresh feature. Make sure it is registered before actual react scripts.

import { viteReactRefresh, viteAssets } from 'adonisjsx'

function MyComponent() {
  return (
    <html>
      <head>
        {viteReactRefresh()}
        {viteAssets(['resources/js/app.js'])}
      </head>
      <body>
        <div>Hello World</div>
      </body>
    </html>
  )
}

csrfField

With @adonisjs/shield installed, you can use csrfField method to generate a hidden input with csrf token.

import { csrfField } from 'adonisjsx'

function Form() {
  return (
    <form>
      {csrfField()}
      <button>Submit</button>
    </form>
  )
}

route

You can use route method to generate urls for your routes. It works the same way as in edge templates.

// routes.tsx
import router from "@adonisjs/core/services/router";

router.get('/foo', async () => {
  return "foo"
}).as('foo')

// MyComponent.tsx
import {route} from 'adonisjsx'

function MyComponent() {
  return (
    <a href={route('foo')}>Home</a>
  )
}

Recipes

Code samples that will help you move from edge templating.

Get http context inside the component

You may need to access request or other HttpContext metadata inside your component. You can do that by calling HttpContext.getOrFail method.

function MyComponent() {
  const { request } = HttpContext.getOrFail()
  return <div>{request.ip()}</div>
}

License

Adonisjsx is open-sourced software licensed under the MIT license.