uws-autoload

uws-autoload

Plugin for µWebSockets.js that autoloads all routes in a directory.

Inspired by elysia-autoload.

Installation

yarn add uws-autoload

Usage

Register the Plugin

import { App } from 'uWebSockets.js'
import { autoloadRoutes } from 'uws-autoload'

const port = +(process.env.PORT || 3000)

const app = await autoloadRoutes(App(), {
  // Pattern to scan route files
  pattern: '**/*.ts',
  // Prefix to add to routes
  prefix: '/api',
  // Source directory of route files: use "relative" path
  routesDir: './src/api'
})

app.listen(port, (listenSocket) => {
  if (listenSocket) {
    console.log(`Server running at http://localhost:${port}`)
  } else {
    console.log(`Failed to listen to port ${port}`)
  }
})

Create a Route

// /routes/index.ts
import type { TemplatedApp } from 'uWebSockets.js'

export default ((res, req) => {
  res.end('Hello World!')
}) satisfies Parameters<TemplatedApp['get']>[1]

Directory Structure

Guide on how uws-autoload matches routes:

├── app.ts
├── routes
│   ├── index.ts         // index routes
│   ├── posts
│   │   ├── index.ts
│   │   └── [id].ts      // dynamic params
│   ├── likes
│   │   └── [...].ts     // wildcard
│   ├── domains
│   │   ├── @[...]       // wildcard with @ prefix
│   │   │   └── index.ts
│   ├── frontend
│   │   └── index.tsx    // usage of tsx extension
│   ├── events
│   │   ├── (post).ts    // post and get will not be in the link
│   │   └── (get).ts
│   └── users.ts
└── package.json

• /routes/index.ts → /
• /routes/posts/index.ts → /posts
• /routes/posts/[id].ts → /posts/:id
• /routes/users.ts → /users
• /routes/likes/[...].ts → /likes/*
• /routes/domains/@[...]/index.ts → /domains/@*
• /routes/frontend/index.tsx → /frontend
• /routes/events/(post).ts → /events
• /routes/events/(get).ts → /events

Options

Key	Type	Default	Description
failGlob?	boolean	true	Throws an error if no matches are found
importKey?	string	default	The key (name) of the exported function of route files
pattern?	string	**/*.{ts,tsx,js,jsx,mjs,cjs}	Glob patterns
prefix?	string		Prefix to be added to each route
routesDir?	string	./routes	The folder where routes are located (use a relative path)
skipImportErrors?	boolean	false	Throws an error if there is an import error of a route file

Transpile

For Vite + Node.js and similar use cases, where .ts or .tsx files aren't transpiled, install esbuild.

Note:

Bun internally transpiles every file it executes (both .js and .ts) → Read more

License

This project is licensed under the MIT License.