Module
A React Framework for Deno that makes it easy to create highly interactive apps that have server side rendering with file based routing for both your UI and API.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497import { Application, Context, ListenOptions, RouteParams, Router, RouterMiddleware, Status,} from "x/oak/mod.ts";import { ComponentType, Context as ReactContext, ReactNode, StrictMode,} from "npm/react";import { HelmetContext, HelmetProvider } from "npm/react-helmet-async";import { renderToReadableStream as renderReactToReadableStream } from "npm/react-dom/server";import { createMemoryRouter, RouteObject, RouterProvider,} from "npm/react-router-dom";import serialize from "npm/serialize-javascript";
import { AppErrorContext, HttpError, isHttpError } from "./error.tsx";import { AppEnvironment, createAppContext, getEnv, isBrowser, isDevelopment, isTest,} from "./env.ts";
if (isBrowser()) { throw new Error("Cannot import server.tsx in the browser.");}
const encoder = new TextEncoder();
interface HTMLOptions< AppContext extends Record<string, unknown> = Record<string, unknown>,> { helmet: HelmetContext.HelmetServerState; env: AppEnvironment; context: AppContext; devPort?: number; error?: HttpError<{ boundary?: string }>;}
function html< AppContext extends Record<string, unknown> = Record<string, unknown>,>( { helmet, env, context, devPort, error }: HTMLOptions<AppContext>,) { const headTags = [ helmet.base.toString(), helmet.title.toString(), helmet.priority.toString(), helmet.meta.toString(), helmet.link.toString(), helmet.style.toString(), helmet.script.toString(), `<script> window.app = { env: ${serialize(env, { isJSON: true })}, context: ${serialize(context, { isJSON: true })}, }; </script>`, error && `<script>window.app.error = ${serialize(HttpError.json(error))};</script>`, isDevelopment() && devPort && `<script>window.app.devPort = ${ serialize(devPort, { isJSON: true }) };</script>`, isDevelopment() && `<script src="/live-reload.js"></script>`, helmet.noscript.toString(), ].filter((tag: string) => Boolean(tag));
return { start: `\<!DOCTYPE html><html ${helmet.htmlAttributes.toString()}> <head> ${headTags.join("\n ")} <script type="module" src="/${ isTest() ? "test-" : "" }build/app.js" defer></script> </head> <body ${helmet.bodyAttributes.toString()}>`, end: ` </body></html>`, };}
/** * The default renderToReadableStream function. * If you'd like to transform the stream before it is returned to the client, * you can wrap this function with a custom renderToReadableStream function. */export async function renderToReadableStream< AppContext extends Record<string, unknown> = Record<string, unknown>,>( context: Context<AppState<AppContext>>,) { const { request, state } = context; const { route, providerFactory, Context } = state._app; const Provider = providerFactory(context); const { env, context: appContext, error, devPort } = state.app; const { pathname, search } = request.url; const location = `${pathname}${search}`; const helmetContext = {} as HelmetContext;
const router = createMemoryRouter([route], { initialEntries: [location], });
const stream = await renderReactToReadableStream( <StrictMode> <HelmetProvider context={helmetContext}> <AppErrorContext.Provider value={{ error }}> <Context.Provider value={appContext}> <Provider> <RouterProvider router={router} /> </Provider> </Context.Provider> </AppErrorContext.Provider> </HelmetProvider> </StrictMode>, { onError(error: unknown) { console.error("renderToReadableStream error", error); }, }, ); await stream.allReady;
const { start, end } = html({ helmet: helmetContext.helmet, env, context: appContext, error, devPort, });
return stream .pipeThrough( new TransformStream({ start(controller) { controller.enqueue(encoder.encode(start)); }, flush(controller) { controller.enqueue(encoder.encode(end)); }, }), );}
export interface AppState<AppContext = Record<string, unknown>> { /** For internal use only. */ _app: { route: RouteObject; providerFactory: ( context: Context<AppState<AppContext>>, ) => ComponentType<{ children: ReactNode }>; Context: ReactContext<AppContext>; }; /** A container for application data and functions. */ app: { /** * Environment variables that will be shared with the browser. */ env: AppEnvironment; /** * A container for your application's own data that is serialized and sent to the browser. * It can be accessed via AppContext. */ context: AppContext; /** Renders the application to a readable stream and responds to the request with it. */ render: () => Promise<void>; /** The port for the dev script's live reload server. */ devPort?: number; /** * If an error occurs when handling the request, this will be set to that error. * The error will be serialized and sent to the browser. * The browser will recreate the error for an AppErrorBoundary to catch. * If the server error is not getting caught, the boundary doesn't match the AppErrorBoundary you expect to catch it. */ error?: HttpError<{ boundary?: string }>; };}
function defaultProviderFactory< AppContext extends Record<string, unknown> = Record<string, unknown>,>( context: Context<AppState<AppContext>>,): ComponentType<{ children: ReactNode }> { return (({ children }) => <>{children}</>);}
export interface AppRouterOptions< AppContext extends Record<string, unknown> = Record<string, unknown>,> { /** * A react router route object. * The build script will automatically generate these for your application's routes. * The route object is a default export from the `_main.tsx` in your routes directory. */ route: RouteObject; /** * Default environment variables that you would like to share with the browser for all requests. */ env?: AppEnvironment; /** Creates a provider around the application. */ providerFactory?: ( context: Context<AppState<AppContext>>, ) => ComponentType<{ children: ReactNode }>; /** A context object for the App. State stored within the AppContext will be serialized and shared with the browser. */ Context?: ReactContext<AppContext>; /** * Used to render the application. * If you'd like to transform the stream before it is returned to the client, * you can wrap the default renderToReadableStream function with a custom renderToReadableStream function. */ renderToReadableStream?: typeof renderToReadableStream<AppContext>; /** * The oak router for your application. * The build script will automatically generate these for your application's routes. * The router object is a default export from the `_main.ts` in your routes directory. */ router?: Router; /** * The working directory of your application. * Defaults to the current working directory that your application is running from. */ workingDirectory?: string; /** The port for the dev script's live reload server. */ devPort?: number;}
const TRAILING_SLASHES = /\/+$/;
/** * Creates an oak router for your application. */export function createAppRouter< AppContext extends Record<string, unknown> = Record<string, unknown>,>( { route, env, providerFactory, Context, renderToReadableStream: renderAppToReadableStream, router, workingDirectory, devPort, }: AppRouterOptions<AppContext>,) { renderAppToReadableStream ??= renderToReadableStream; router ??= new Router(); workingDirectory ??= Deno.cwd(); providerFactory ??= defaultProviderFactory; Context ??= createAppContext<AppContext>();
const appRouter = new Router() .use(async (context, next) => { const { request, response } = context; const { pathname, search } = request.url; if (pathname.length > 1 && pathname.at(-1) === "/") { response.status = 301; response.redirect(pathname.replace(TRAILING_SLASHES, "") + search); } else { await next(); } }) .use(async (context: Context<AppState<AppContext>>, next) => { const { request, response, state } = context; try { if (!state.app) { state._app = { route, providerFactory: providerFactory!, Context: Context!, }; state.app = { env: { APP_ENV: getEnv("APP_ENV"), ...env, }, context: {} as AppContext, render: async () => { response.type = "html"; response.body = await renderAppToReadableStream!(context); }, }; if (isDevelopment() && devPort) { state.app.devPort = devPort; } } await next(); } catch (cause) { const error = HttpError.from(cause); console.error("app error", error);
response.status = error.status; state.app.error = error; await state.app.render(); } }) .use(router.routes(), router.allowedMethods());
if (isDevelopment()) { let liveReloadScript = ""; appRouter.use(async (context, next) => { const { request, response } = context; if (request.url.pathname === "/live-reload.js") { if (!liveReloadScript) { liveReloadScript = await (await fetch( new URL("./live-reload.js", import.meta.url), )).text(); } response.headers.set("Content-Type", "text/javascript"); response.body = liveReloadScript; } else { await next(); } }); }
appRouter.get("/(.*)", async (context) => { try { await context.send({ root: `${workingDirectory}/public` }); } catch (cause) { if (isHttpError(cause) && cause.status === Status.NotFound) { throw new HttpError(404, "Not found", { cause }); } else { throw cause; } } });
return appRouter;}
/** Creates a Udibo React App. */export function createApp< AppContext extends Record<string, unknown> = Record<string, unknown>,>(options: AppRouterOptions<AppContext>) { const app = new Application();
const appRouter = createAppRouter(options);
app.use(appRouter.routes(), appRouter.allowedMethods());
return app;}
/** * This function tells the dev server when the app server is listening. * If you are not using serve, you must add an event listener to your app that will call this function once it's listening. * If this function is not called, the browser will not automatically refresh when the app server is restarted. * If called before the app server is listening, the browser will refresh before the app server is ready to handle the request. * This function will not do anything if the app is not running in development mode. */export async function listeningDev( { hostname, secure, devPort }: { hostname: string; secure: boolean; devPort?: number; },) { if (isDevelopment()) { try { const origin = `${secure ? "https://" : "http://"}${hostname}`; await fetch(`${origin}:${devPort || 9002}/listening`); } catch { // Ignore errors } }}
export interface ServeOptions< AppContext extends Record<string, unknown> = Record<string, unknown>,> extends AppRouterOptions<AppContext> { /** The port your application will listen on. */ port?: number;}
/** Creates and serves a Udibo React App. */export async function serve< AppContext extends Record<string, unknown> = Record<string, unknown>,>({ port, ...options }: ServeOptions<AppContext>) { const app = createApp(options);
app.addEventListener("error", ({ error }) => { console.error("Uncaught app error", error); });
app.addEventListener("listen", ({ hostname, port, secure }) => { const origin = `${secure ? "https://" : "http://"}${hostname}`; console.log(`Listening on: ${origin}:${port}`); queueMicrotask(() => listeningDev({ hostname, secure, devPort: options.devPort }) ); });
const listenOptions = {} as ListenOptions; if (typeof port === "number") listenOptions.port = port; await app.listen(listenOptions);}
/** * Wraps an API router with an error handler that responds with the error in json format. */export function createApiRouter(router: Router) { return new Router() .use(async ({ response }, next) => { try { await next(); } catch (cause) { const error = HttpError.from(cause); console.error("api error", error);
response.status = error.status; response.body = HttpError.json(error); } }) .use(router.routes(), router.allowedMethods());}
/** * For internal use only. * This router renders the application on get requests. * It is used for all route components that do not have route middleware. */export const defaultRouter = new Router() .get("/", async (context: Context<AppState>) => { await context.state.app.render(); });
/** * This middleware ensures all errors in the route are HttpErrors. * If an error isn't an HttpError, a new HttpError is created with it as the cause. * If a boundary is specified, it will add the boundary to the HttpError. * If an AppErrorBoundary exists with a matching boundary, it will be used to handle the error. * If a boundary is not specified, the first AppErrorBoundary without a boundary specified will handle the error. * If a boundary is specified, but no AppErrorBoundary exists with a matching boundary, the error will go unhandled. * * By default, any route that has an ErrorFallback will have an errorBoundary automatically added to it. * The automatic error boundaries name will match the route. * You can add your own error boundaries anywhere. * * To ensure an error boundary catches the error, your router needs to use this middleware. * * ```ts * const router = new Router() * .use(errorBoundary("MyComponentErrorBoundary")) * ``` * * Then the related react component for the route needs to either use `withAppErrorBoundary` or `AppErrorBoundary` to be able to catch the error during rendering. * The boundary identifier must match the one on the server. * * ```tsx * const MyComponentSafe = withAppErrorBoundary(MyComponent, { * FallbackComponent: DefaultErrorFallback, * boundary: "MyComponentErrorBoundary" * }) * ``` * * ```tsx * <AppErrorBoundary FallbackComponent={DefaultErrorFallback} boundary="MyComponentErrorBoundary"> * <MyComponent /> * </AppErrorBoundary> * ``` */export function errorBoundary< P extends RouteParams<string> = RouteParams<string>, S extends AppState = AppState,>(boundary?: string): RouterMiddleware<string, P, S> { return async (context, next) => { const { response, state } = context; const { app } = state; try { await next(); } catch (cause) { const error = HttpError.from<{ boundary?: string }>(cause); app.error = error; if (boundary) error.data.boundary = boundary; response.status = error.status; await state.app.render(); } };}