💎 Quickstart

A (mostly) blank project

git clone https://github.com/exhibitionist-digital/create-ultra-app
cd create-ultra-app
deno task dev

If you want to dive right in, create-ultra-app is the easiest way. Less words, more ESM.

Steal this website

git clone https://github.com/exhibitionist-digital/ultra-examples
cd ultra-examples
deno task dev

More examples are found in the following branches in the ultra-examples repo: react-18, three-js, web3

Anatomy of an Ultra project

This is the bare minimum for an Ultra project.

• server.ts
• src/app.tsx
• importMap.json
• deno.json

server.ts

This code runs Ultra's server:

import ultra from "https://deno.land/x/ultra/server.ts";

await ultra();

importMap.json

Here we include the dependencies of the project:

{
  "imports": {
    "react": "https://esm.sh/react@18",
    "react-dom": "https://esm.sh/react-dom@18",
    "react-dom/server": "https://esm.sh/react-dom@18/server",
    "react-helmet": "https://esm.sh/react-helmet-async?deps=react@18",
    "wouter": "https://esm.sh/wouter?deps=react@18",
    "swr": "https://esm.sh/swr?deps=react@18",
    "ultra/cache": "https://deno.land/x/ultra@v0.8.0/cache.js",
    "app": "./src/app.tsx"
  }
}

The above imports are all required to run Ultra. You can add other dependencies here, and use the import keys as an import alias in your project code (see import maps section in the Deno manual).

app is the entry point to your application. It can live anywhere in the src directory. It can be jsx or tsx.

src

All of your project code should live in the src directory. The only requirement is an app.tsx/jsx file, which is included in your importmap above. Feel free to structure your project how you like. Static files (css, images, etc) can be placed in this directory as well, and will be served as the root of your domain.

src/app.tsx

import React,  from "react";
import { SWRConfig } from "swr";
import { Link, Route, Switch } from "wouter";
import { Helmet } from "react-helmet";
import ultraCache from "ultra/cache";
import { Cache } from "https://deno.land/x/ultra/src/types.ts";

const options = (cache: Cache) => ({
  provider: () => ultraCache(cache),
  suspense: true,
});

export default const Ultra = ({ cache }: { cache: Cache }) => {
  return (
    <SWRConfig value={options(cache)}>
      <Helmet>
        <title>Ultra</title>
      </Helmet>
      <main>
        <Switch>
          <Route path="/">
            <h1>Homepage</h1>
          </Route>
          <Route>
            <h1>404</h1>
          </Route>
        </Switch>
      </main>
    </SWRConfig>
  );
};

1. File extensions are important. Always include .tsx/.jsx in your import statements.
2. The ultraCache function populates the server-side cache and rehydrates the client-side cache. It is not needed unless you are using Suspense or SWR.

deno.json

Using the native Deno config, ensure you specify your importMap path here, as well as any common tasks.

{
  "tasks": {
    "dev": "mode=dev deno run -A --unstable --no-check server.js",
    "start": "deno run -A --unstable server.js",
    "cache": "deno cache --reload server.js",
    "vendor": "importMap=importMap.json deno run -A --unstable https://deno.land/x/ultra/vendor.ts",
  },
  "importMap": "importMap.json"
}

Defined Tasks:

• dev - Always forces re-importing of ESM files, enabled reload on save.
• start - Production mode that uses cached ESM imports.
• cache - Refreshes the deno cache for server.js.
• vendor - See Vendoring below.

Permissions

In production, instead of -A, define all the utilized permissions with appropriate values to take full advantage of Deno's permission-based security. Ultra uses the following permissions: allow-net, allow-read, allow-env, allow-write.

allow-env

Add these Ultra used environmental variables to the list of custom ones that you use (in a comma-separated list):

allow-read

Add ./.ultra,./importMap.json to the list of directories or files that you use.

allow-write

Add ./.ultra to the list of directories or files that you use.

allow-net

Add https://deno.land/x/ultra/ to the list of internet Urls that you use.

Suspense data fetching

Vercel's SWR lets us fetch data anywhere in our components and works with Suspense. Ultra uses the brand new SWR 1.0.0+.

All SWR options are supported SWR docs.

import { SWRConfig } from "swr";
import ultraCache from "ultra/cache";

const options = (cache) => ({
  provider: () => ultraCache(cache),
  suspense: true,
});

const Ultra = ({ cache }) => {
  return (
    <SWRConfig value={options(cache)}>
      <h1>Hello World</h1>
    </SWRConfig>
  );
};

Routing

Powered by Wouter. Wouter is fully-featured, tiny (1.36 KB), and the best React router that we've ever used. Ultra comes with a server side integration which allows full functionality of Wouter.

All Wouter hooks and functionality is supported Wouter docs.

import React, { Suspense } from "react";
import { Route } from "wouter";

const Home = lazy(() => import("./home.jsx"));

const App = () => {
  return (
    <Route path="/">
      <Home />
    </Route>
  );
};

Head

Powered by react-helmet-async. It is used to add markup to the html <head> element such as <title>, <meta> and <link> tags.

import React from "react";
import { Helmet } from "react-helmet";

const App = () => {
  return (
    <Helmet>
      <title>Ultra</title>
    </Helmet>
  );
};

Service Workers

We recommend the usage of vanilla Service Workers in your Ultra app. An incredibly powerful tool to help with the serving, caching, and optimisation of your website. Use them carefully.

MDN Docs for Service Workers

Here is an example that is currently used on this site: Ultrajs Service Worker

Dynamic MDX

Ultra supports using MDX dynamically.

MDX on demand

In fact, this very text was generated with dynamic MDX.

We have a plugin that will make any of your local component imports work inside of Ultra. This is how an basic API route could look...

MDX API route

import { compile } from "https://esm.sh/@mdx-js/mdx/lib/compile";
import ultraMdx from "https://deno.land/x/ultra/ultraMdx.ts";

export default async () => {
  const source = await Deno.readTextFile(
    `${Deno.cwd()}/src/YOUR_MDX_FILE.mdx`,
  );

  const content = String(
    await compile(source, {
      outputFormat: "function-body",
      useDynamicImport: true,
      rehypePlugins: [ultraMdx],
    }),
  );
  const body = JSON.stringify({ content });
  return new Response(body);
};

MDX JSX template

// Ensure you only import `run` to keep client size to a minimum
import { runSync } from "https://esm.sh/@mdx-js/mdx/lib/run";
import * as runtime from "https://esm.sh/react@v18.0.0/jsx-runtime.js";

const Component = () => {
  // Fetch the content from the API route above
  const { data } = useSWR("/YOUR_API_ROUTE", fetcher);
  // and use runSync on it
  const { default: Content } = runSync(data.content, runtime);
  // Use Content like a standard React component
  return <Content />;
};

Vendoring

During development, it's helpful to utilise CDNs like esm.sh, unpkg.com, and deno.land/x to serve your projects dependencies. When deploying to production, you may want to forego the CDNs and serve your dependencies locally. We have a script for doing this encapsulated in the vendor task defined in deno.json:

importMap=importMap.json deno run -A --unstable https://deno.land/x/ultra/vendor.ts

This will download a complete graph of your dependencies to a .ultra/x directory, as well as create a vendorMap.json import map file. You can then define this new import map in your deno.json file to swap to local dependencies.

As of v0.8.0, all projects deployed to Deno Deploy will have this feature enabled by default.

Deploying

With Docker/Fly

dockerfile

This is an example dockerfile which supports vendored dependencies.

FROM denoland/deno:1.20.3
EXPOSE 8000
RUN apt-get update
RUN apt-get install -y jq moreutils
WORKDIR /
COPY . .
RUN deno task vendor
RUN jq '.importMap = "./vendorMap.json"' deno.json|sponge deno.json
CMD ["deno", "task", "start"]

With Deno Deploy

Ultra supports the official Deno Deploy GitHub Action!

1. Create a project in the Deno Deploy Dashboard
2. Select GitHub Action integration
3. Add the following action to your project. (Note to update the root and project name)

Note: Deno Deploy does NOT support dynamic imports (yet). If you are using these for routing, the project will not deploy.

name: deno deploy
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    name: deploy
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Clone repository
        uses: actions/checkout@v2

      - name: Install Deno
        uses: denoland/setup-deno@main
        with:
          deno-version: 1.20.3

      - name: Build site
        run: root=https://example.com deno run -A https://deno.land/x/ultra/build.ts

      - name: Upload to Deno Deploy
        uses: denoland/deployctl@v1
        with:
          project: [PROJECT_NAME]
          entrypoint: ULTRA.js
          root: .ultra