Concepts

Routing

adex core functionality is that of a router, it creates route bindings for pages and api's.

Route bindings can be created simply by creating a file in the src/pages or src/api folder.

Pages

Pages or files inside src/pages are components that define a view. A view is what the user sees and so this is where you write the user facing elements for adex. Each route is bound to a similar path in the pages folder.

Eg: src/pages/hello.js would be accessed as /hello in the browser.

Rules

• The page needs a default export which defines the view
• Server sided code should not be executed in pages, they are strictly client sided views.

API Routes

The other side of the application is to handle server side data which can be sent from the API routes. These route bindings are created by adding files to the src/api directory.

Eg: src/api/hello.js would be bound to /api/hello

API route files need to export simple node:http handlers.

export default function handler(req, res) {
  return res.write("hello world");
}

API Helpers

Since a lot of what we write get's redundant while working with web apps, a few helpers are added to the request and response references

Response Helpers

• text - for plain text responses
• json - for serialized json responses
• html - for html strings

Request Helpers

• parseBodyJSON - to parse the request body as JSON

Examples

// JSON Response
export default function handler(req, res) {
  return res.json({
    ping: "pong",
  });
}

export default async function handler(req, res) {
  if (req.method !== "POST") {
    res.statusCode = 404;
    return res.end();
  }
  const payload = await req.parseBodyJSON();
  return res.json({
    ...payload,
  });
}

Islands

This is an additional feature of adex that significantly changes how the views are rendered. Instead of rendering fully interactive pages, you now render static pages with interactive bits.

This replicates a similar feature set to Deno's fresh except you don't need to define a separate folder for islands, you just write them as components and adex will take care of identifying them.

You can read more about the concept on preactjs.com/blog/simplifying-islands-arch.

To enable this you pass the islands option as true in the adex plugin

// vite.config.js
import { defineConfig } from "adex";

export default defineConfig({
  //...remaining config
  plugins: [
    //...remaining plugins
    adex({
      islands: true,
    }),
  ],
});

Caveats

Existing pages that were interactive will become static and will not bind any events or state handlers. The sub components that are interactive will stay interactive

For other options checkout the configuration reference