Introduction to Aleph - The React Framework in Deno

Aleph is a JavaScript framework that offers you the best developer experience in building modern web applications with React while using Deno for server-side operations.

Aleph allows you to build React application that uses server-side rendering by default. Since it uses Deno, it doesn’t need to use Webpack for import statements.

This also means you don’t need to install packages to the node_modules folder and write the package.json file. All dependencies can be imported using ESM URL and managed by Aleph.js. For example, you can use the global ESM CDN called esm.sh to import any libraries that you need:

import React from "https://esm.sh/react"

Here are some of the main benefits of using Aleph:

• Zero-configuration framework. No webpack and no package.json
• Supports TypeScript by default
• Using import maps to organize dependencies easier
• Fast Refresh integrated for development
• File-system and API routing, very similar to Next.js
• Built-in Markdown support
• Built-in CSS (LESS and SASS) Support
• Support for SSR and SSG

If you’re already familiar with Next.js, then Aleph will quickly make you feel right at home.

Getting started with Aleph

To get started, you need to have Deno version 1.4 or above installed on your computer.

Note: At the time of this writing, there’s a bug in Deno version 1.7.0 causing Aleph to crash. I’m using Deno version 1.6.3 for this tutorial.

Once you have Deno, you can install Aleph using the deno install command:

deno install -A -f -n aleph https://deno.land/x/aleph@v0.2.28/cli.ts

When the installation is finished, create your first Aleph application with aleph init my-aleph-app.

Inside my-aleph-app directory, you’ll find a number of auto-generated files and directories that make up the structure of an Aleph application:

my-aleph-app
├── app.tsx
├── components
│   └── logo.tsx
├── import_map.json
├── pages
│   └── index.tsx
├── public
│   ├── favicon.ico
│   └── logo.svg
└── style
    └── index.less

Some notes for the folder structure above:

• The public/ folder stores static assets, such as icons, images, and sitemaps
• The pages/ folder is for your application pages
• The components/ folder is for any shared React components that you can use in your pages
• The style/ folder will store all your CSS code
• The app.tsx file serves as the entry point of your Aleph application

Once the application has been created, move into the my-aleph-app directory and run your Aleph app with the aleph devcommand.

Navigate to your http://localhost:8080/ to see your Aleph index page:

Aleph index page

Aleph supports TypeScript with Deno and uses the .tsx file extension for all its generated files. The code for the index page above is at pages/index.tsx.

Build Great Design Systems and Micro Frontends

Take frontend development to the next level with independent components. Build and collaborate on component-driven apps to easily unlocks Micro Frontends, and to share components.

OSS Tools like Bit offer a great dev experience for building and composing independent components, and build solo or together with your team.

Give it a try →

An independently source-controlled and shared “card” component. On the right => its dependency graph, auto-generated by Bit.

ESM quick compile with Aleph

The ES modules required by your application will be downloaded when you run the aleph dev command. Every downloaded module only needs to be compiled once and then cached on the disk.

When a module changes, Aleph.js just needs to re-compile that single module, so there’s no time wasted for re-bundling modules with no change. Because you don’t need to npm install new modules or libraries, any new import that you write in your code will make Aleph download that module and quickly compile it for you.

Once the compilation is finished, Aleph instantly updates the browser by using the HMR (Hot Module Replacement) technology with React Fast Refresh.

For example, let’s say you want to add the date_fns module to Aleph. While your development server is still running, you can edit your default pages/index.tsx file with the code below:

import React from "https://esm.sh/react"
import { format } from 'https://deno.land/x/date_fns/index.js'
export default function Home() {
  return <h1>{format(new Date(2014, 1, 11), 'yyyy-MM-dd')}</h1>
}

Then save your changes. You will see in the console that Aleph will automatically download the required modules and refresh your page in the browser. You don’t need to stop your development server just to npm install libraries.

Creating Aleph pages

The concept of pages in Aleph is the same as in Next.js, where each single valid React component file under the .js, .jsx, .ts, .tsx, or .mjs extensions will be mapped to /* routes. For example, pages/about.js will map to /about route:

import React from "https://esm.sh/react"
export default function About() {
  return <h1>About Us</h1>
}

You also can create a markdown page by using the .md extension for your page:

---
title: About
description: My about page
---
# About

The above file will be transformed into a React component page as follows:

import React from "https://esm.sh/react"
export default function MarkdownPage() {
  return (
    <>
      <h1>About</h1>
      <p>Hello Everyone, this is my about page</p>
    </>
  )
}
MarkdownPage.meta = {
  title: "About",
  description: "My about page"
}

Aleph also supports dynamic page using the pages/route/[param].extension naming pattern. You can then grab the parameter using the useRouter hook from Aleph.

Here’s an example of creating a dynamic page route named aspages/user/[id].js:

import React from "https://esm.sh/react"
import { useRouter } from "https://deno.land/x/aleph/mod.ts"
export default function User() {
  const { params } = useRouter()
  return <h1>{params.id}</h1>
}

The above code will be

When you want to fetch data from API endpoints for the page, you need to use the provided useDeno hook:

import React from "https://esm.sh/react"
import { useDeno, useRouter } from "https://deno.land/x/aleph/mod.ts"
export default function User() {
  const { params } = useRouter() // grab the parameter
const post = useDeno(async () => {
    return await (await fetch(`https://.../user/${params.id}`)).json()
  })
return (
    <h1>{post.title}</h1>
  )
}

By default, the useDeno hook call will only be executed during build time, with the response cached on the disk. When the hook is called on the browser, Aleph will simply return the cached data without fetching the endpoint again.

If you want Aleph to actively fetch data with each page refresh, you need to pass two parameters into the hook:

The second parameter is a boolean value true to let Aleph know that you want a new fetch with every refresh:

const post = useDeno(async () => {
    return await (await fetch(`https://.../user/${params.id}`)).json()
  }, true)

And the third parameter is the dependency array to observe the parameter change that will trigger the fetch call, just like in a useEffect hook:

const post = useDeno(async () => {
    return await (await fetch(`https://.../user/${params.id}`)).json()
  }, true, [params.id])

For more details, see the useDeno hook documentation.

API route support

When you need to create an API endpoint for your Aleph application, you simply need to create the api/ folder in your project’s root folder. Any file(.ts,.js,.mjs) inside the folder will be mapped to /api/* route.

To accept incoming requests to your API route, you need to export as default a function that receives the APIRequest object:

import type { APIRequest } from "https://deno.land/x/aleph/types.ts"
export default function handler(req: APIRequest) {
  req.status(200).json({ name: 'Carol' })
}

The API route also supports dynamic routing like in the pages.

Using import maps for modules

You can use import maps in Aleph by creating an import_map.json file in the application root directory:

{
  "imports": {
    "react": "https://esm.sh/react",
    ...
  }
}

Then you can import react into your files as follows:

import React from "react"
export default function About() {
  return <h1>About</h1>
}

But keep in mind that you need to enable Deno support for import maps to make this work because the feature is currently under “unstable features” label.

If you’re using VSCode, please add the below settings in .vscode/settings.json file:

{
  "deno.enable": true,
  "deno.unstable": true,
  "deno.import_map": "./import_map.json"
}

Conclusion

Aleph is a unique JavaScript framework that enables developers to build their web applications using React and Deno.

By using Deno for its server-side operations, Aleph doesn’t need to install libraries in a node_modules folder, eliminating the need for a package.json file to list its dependencies. It also doesn’t need to use Webpack to process assets or importing libraries, giving a zero-configuration framework experience.

For further information, checkout Aleph’s documentation at https://alephjs.org/docs

Learn More

What is Deno and will it Replace NodeJS?

Build Scalable React Apps by Sharing UIs and Hooks

Design Systems with React’s Server, Shared and Client Components