Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



A Next.js style dynamic API router for Koa-based APIs.

Version published
Weekly downloads
increased by50%
Install size
8.23 MB
Weekly downloads




npm version

Installation   |   Get Started   |   Examples   |   Contributions

What is 18h?

18h is a Next.js-inspired Koa-router wrapper, which allows you to create routes that match the pattern of your filesystem. This speeds up iteration, while maintaining a serverful architecture.

This library is best used with Node.js & TypeScript in order to unlock all the type-safety capabilities it has to offer.

Why is it named 18h?

That is how long Koala's sleep, and all the cooler names were taken.

Get Started

Getting started is pretty snappy.


In order to install the package, in your root directory simply use your favourite package manager in order to install the package. It is registered on the NPM under the name 18h.

npm install 18h

Creating the Router

First, using your favourite file manager, or the command line, create the folder in which your routes will be stored in. This folder will mirror the structure of your API.

mkdir routes

Once this is complete, we will be able to instantiate our router object by referencing this folder. It's best practice to use the Node.js path module, along with the global __dirname constant in order to ensure the application runs correctly once it is transpiled to JavaScript.

import { join } from "path";
import { router } from "18h";

  routesFolder: join(__dirname, "routes"),
  port: 8000,
  hostname: "localhost",

We can also instantiate the 18h router with global middleware that will run prior to every API call.

const logRequest = async (context, next) => {
  await next();

  // ...
  middleware: [logRequest],

Creating Routes

Its important to remember that the structure of the filesystem within the routes folder you provide as the routesFolder key is going to mirror the structure of your URLs.


Assuming you provided a folder called routes as the routesFolder when creating your router object, creating a file at routes/index.ts it will allow consumers to interact with that endpoint at the http://localhost/ URL.

Creating a file called routes/example.ts will allow consumers to interact with that endpoint at the http://localhost/example URL.

Creating a file called routes/example/index.ts will produce the same result as mentioned above.


Placing square brackets [] around the entire name of a folder or file in the routes folder will allow for route parameters to be accepted through that endpoint.

/a/[b]/c would become the endpoint path /a/:b/c.

The following file structure would generate the corresponding API endpoint structure.

File Structure
├── index.ts
└── routes/
    ├── index.ts
    ├── feed/
    │   └── index.ts
    ├── user/
    │   ├── delete.ts
    │   ├── index.ts
    │   └── settings/
    │       ├── private.ts
    │       └── name.ts
    ├── users/
    │   └── [userId]/
    │       ├── block.ts
    │       ├── index.ts
    │       └── follow.ts
    └── posts/
        ├── create.ts
        ├── delete.ts
        ├── index.ts
        ├── like.ts
        └── share.ts
Resulting API Path Structure
Adding Logic to Paths

Of course, we want the paths to do things when someone interacts with them, that logic is defined in RouteController object, which takes multiple MethodControllers in which we define the logic of that endpoint.

Let's start off by creating the logic for the /users/[userId]/block endpoint so we can get a better feel for all the features.

// src/routes/users/[userId]/block

import { route, method, validation } from "18h";

export default route<{ userId: string }>({
  get: method({
    /** If you are accepting a body, you must
     * define whether it can be `"form"`,
     * `"json"`, or both. */
    // accepts: ["json", "form"],
    /** Validation, request, and response schema
     * definition is done in one swoop. Uses "zod"
     * library under the hood. */
    schema: {
      request: validation.null(),
      response: validation.object({
        userId: validation.string(),
    /** Optional middleware, `pre` will occur
     * before the hanler, while `post` will happen
     * after. */
    middleware: {
      pre: [],
      post: [],
    async handler(context) {
      console.log(context.params.userId); // :userId sourced from URL.
      console.log(context.request.body); // null

      return {
        status: 200,
        headers: {
          "x-custom-header": "true",
        body: {
          userId: "some_id",


We can create a simple endpoint that just responds with the node package version of the current project we're in. The endpoint will work on all HTTP methods, not just GET, but we could change it to do that by changing all occurances of all to get.

import { route, method, validation } from "18h";
const { npm_package_version: version } = process.env;

export default route({
  all: method({
    schema: {
      request: validation.null(),
      response: validation.object({
        version: validation.string().optional(),
    async handler() {
      return { body: { version } };


Contributions are welcome! Happy hacking! 🎉



Last updated on 15 Oct 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc