Package Exports

@microeinhundert/radonis

Readme

Radonis

Easily bridge the gap between your React frontend and AdonisJS backend. Get DX similar to Remix while having the power of AdonisJS at your fingertips.

Features:

Render React views directly from AdonisJS routes and controllers
Partially hydrate only the components that require interactivity on the client (Islands Architecture)
Includes pre-made hooks for working with AdonisJS inside your React views, both on client and server
Ships with a compiler powered by esbuild, no Webpack Encore required
Styling with Twind built in

Requirements:

@adonisjs/core ^5.7.0
@adonisjs/session ^6.2.0
@adonisjs/shield ^7.0.0
@adonisjs/i18n ^1.5.0
react ^18.0.0
react-dom ^18.0.0

Getting Started

1. Install the package

Install the package from your command line:

npm install --save @microeinhundert/radonis

2. Configure the server package

node ace configure @microeinhundert/radonis-server

3. Install required AdonisJS addons

Install and configure the required AdonisJS addons if not already done:

npm install --save @adonisjs/i18n
node ace configure @adonisjs/i18n

and

npm install --save @adonisjs/session
node ace configure @adonisjs/session

and

npm install --save @adonisjs/shield
node ace configure @adonisjs/shield

4. Install React

npm install --save react react-dom
npm install --save-dev @types/react @types/react-dom

5. Configure TypeScript

Add the following to the compilerOptions of your tsconfig:

{
  "compilerOptions": {
    "jsx": "react"
  }
}

Server-Side Templating

Instead of Edge, Radonis uses React to render views on the server. This makes it possible to use the same templating language on both server and client.

Usage in controllers:

import type { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'
import { Index, Show } from '../../../resources/views/Users.tsx' // Where you put your views and how you structure them is completely your choice

export default class UsersController {
  public index({ radonis }: HttpContextContract) {
    return radonis.render(Index)
  }

  public show({ radonis }: HttpContextContract) {
    return radonis.render(Show)
  }
}

Usage in routes:

import Route from '@ioc:Adonis/Core/Route'
import { SignUp } from '../resources/views/Auth.tsx'

Route.get('/signUp', async ({ radonis }) => {
  return radonis.render(SignUp)
})

Using Client-Side Hydration

Radonis uses partial hydration to only hydrate what is needed. In order for Radonis to know what to hydrate on the client, wrap the individual components with the HydrationRoot component:

import { HydrationRoot } from '@ioc:Adonis/Addons/Radonis'

function ServerRenderedComponent() {
  return (
    <HydrationRoot componentName="SomeInteractiveComponent">
      <SomeInteractiveComponent someProp="test">This component will be hydrated client-side</SomeInteractiveComponent>
    </HydrationRoot>
  )
}

Then in your client entry file:

import { initClient } from '@microeinhundert/radonis'

initClient()

Things to keep in mind when working with HydrationRoots:

HydrationRoots only accept a single child. If you want to hydrate multiple parts of your application, use multiple HydrationRoots instead.
All props passed to components inside HydrationRoots must be serializable.
HydrationRoots cannot be nested.
Hydration will only take place once the HydrationRoot is in view.

Hooks

useTwind (Server and client)

import { useTwind } from '@microeinhundert/radonis'

function SomeComponent() {
  const { tx } = useTwind()

  return <div className={tx`text-red-500`}>I am styled using Twind</div>
}

useHydration (Server and client)

import { useHydration } from '@microeinhundert/radonis'

const hydration = useHydration()

// Get info about the HydrationRoot the component is a child of:
console.log(hydration) // => `{ hydrated: false, root: ':Rl6:', componentName: 'SomeInteractiveComponent', propsHash: 'cf5aff6dac00648098a9' }`

// By combining useHydration and useManifest, you can get the props of the component
// passed to the HydrationRoot from any component in the tree:
const hydration = useHydration()
const manifest = useManifest()

console.log(manifest.props[hydration.propsHash]) // => `{ someProp: 'test' }`

useHydrated (Server and client)

This hook allows checking if a component was hydrated.

import { useHydrated } from '@microeinhundert/radonis'

const hydrated = useHydrated()

console.log(hydrated) // => `true` if it was hydrated or `false` if not

useI18n (Server and client)

import { useI18n } from '@microeinhundert/radonis'

const i18n = useI18n()

// Get a translated message:
console.log(i18n.formatMessage('auth.signUpTitle')) // => `Some message defined in translations`

This hook also allows formatting via the ICU message format, just like the official AdonisJS i18n package. Refer to the official AdonisJS Docs for more information about the available formatting rules.

useManifest (Server and client)

import { useManifest } from '@microeinhundert/radonis'

const manifest = useManifest()

// Get the manifest:
console.log(manifest) // => `{ props: {}, flashMessages: {}, locale: 'en', messages: {}, routes: {}, route: {} }`

Please note that the manifest differs between server-side rendering and client-side hydration, therefore don't use this hook inside of components you plan to hydrate on the client. If your use case requires having the same manifest on client and server, set limitManifest to false in the Radonis config.

useRoute (Server and client)

import { useRoute } from '@microeinhundert/radonis'

const route = useRoute()

// Get the current route:
console.log(route.current) // => `{ name: 'users.show', pattern: '/users/:id' }`

// Check if a route is the current route:
console.log(route.isCurrent('users.show')) // => `true` if currently on `users.show` or a child of `users.show`, `false` if not

// Check if exact match:
console.log(route.isCurrent('users.show', true)) // => `true` if currently on `users.show`, `false` if not

useRoutes (Server and client)

import { useRoutes } from '@microeinhundert/radonis'

const routes = useRoutes()

// Get all routes as object:
console.log(routes) // => `{ 'drive.local.serve': '/uploads/*', ... }`

useUrlBuilder (Server and client)

import { useUrlBuilder } from '@microeinhundert/radonis'

const urlBuilder = useUrlBuilder()

// Build the URL for a named route:
const url = urlBuilder.make('signUp') // => `/signUp`

// Build the URL for a controller:
const url = urlBuilder.make('users.index') // => `/users`

// Build the URL with params:
const url = urlBuilder.withParams({ id: 1 }).make('users.show') // => `/users/1`

// You can also provide path params as an array and they will be populated according to their order:
const url = urlBuilder.withParams([1]).make('users.show') // => `/users/1`

// You can also provide query params:
const url = urlBuilder.withQueryParams({ cool: ['adonis', 'react'] }).make('tech.index') // => `/tech?cool=adonis,react

useFlashMessages (Server and client)

import { useFlashMessages } from '@microeinhundert/radonis'

const flashMessages = useFlashMessages()

// Check if a flash message exists:
console.log(flashMessages.has('errors.fieldName.0')) // => `true` or `false`

// Get a flash message:
console.log(flashMessages.get('errors.fieldName.0')) // => `required validation failed on fieldName`

// You can also omit the index to automatically get the first item if an array:
console.log(flashMessages.get('errors.fieldName')) // => same as `errors.fieldName.0`

// You can also get validation errors like this:
console.log(flashMessages.getValidationError('fieldName')) // => same as `errors.fieldName`

// Get all flash messages:
console.log(flashMessages.all()) // => `{ 'errors.fieldName.0': 'required validation failed on fieldName', ... }`

The following hooks align with AdonisJS functionality, refer to the official AdonisJS Docs for usage:

useRadonis (Server only)

Returns info about the AdonisJS instance in the following format:

interface RadonisContextContract {
  application: ApplicationContract
  httpContext: HttpContextContract
  router: RouterContract
}

import { useRadonis } from '@ioc:Adonis/Addons/Radonis'

const radonis = useRadonis()

useApplication (Server only)

Returns the AdonisJS ApplicationContract.

import { useApplication } from '@ioc:Adonis/Addons/Radonis'

const application = useApplication()

useHttpContext (Server only)

Returns the AdonisJS HttpContextContract.

import { useHttpContext } from '@ioc:Adonis/Addons/Radonis'

const httpContext = useHttpContext()

useRequest (Server only)

Returns the AdonisJS RequestContract.

import { useRequest } from '@ioc:Adonis/Addons/Radonis'

const request = useRequest()

useRouter (Server only)

Returns the AdonisJS RouterContract.

import { useRouter } from '@ioc:Adonis/Addons/Radonis'

const router = useRouter()

useSession (Server only)

Returns the AdonisJS SessionContract.

import { useSession } from '@ioc:Adonis/Addons/Radonis'

const session = useSession()

License

MIT