Express-custom NPM

Demo (soon) • Documentation (soon) • Examples • Discord • GitHub

Enhance your express app with builders, Next.js documentation, schema validation, rate-limiting, error handling, and more with this easy-to-use library.

NPM Version NPM Downloads NPM Size

Express custom is a library built on top of express that allows you to easily create and manage your express routes and endpoints. Using this format, you can generate a custom next.js documentation site for your API, export everything to a JSON file, and more.

Some additional features include schema validation, rate-limiting, and error handling.

Warning This library is currently in beta. It is not recommended to use this library in production yet. There may be breaking changes in the future.

Installation

# Using npm
> npm install express-custom
# Using yarn or pnpm
> yarn/pnpm add express-custom

Usage

Importing

This library supports both typescript and javascript, with ES6 modules and CommonJS.

// ES6 modules
import { Api } from 'express-custom';
// CommonJS
const { Api } = require('express-custom');

Create the API

The main class is the Api class. This class is used to create your API and start the server.

It's recommended that you run any functions such as startServer in a seperate main file, and import the API into that file. This is so your application does not run when you use the export commands.

const api = new Api({
  url: 'https://example.com/api',
  port: 5000,
});

// In the main file
const server = api.start(() => {
  console.log('Server started on port 5000');
});

Add a version to the API

To add a version to your API, use the addVersion function. This function takes a Version object. The Version class is used to create a version for your API. You can add multiple versions to your API.

The version number must be a number. The version number is used in the url to access the version. For example, if you have a version with the number 1, the url to access that version would be https://example.com/api/v1.

const v1 = new Version({
  version: 1,
});

// Add groups, routes and endpoints to the version ...

api.addVersion(v1);

Add a group to the version

To add a group to your API, use the addGroup function. This function takes a Group object. The Group class is used to create a group for your API. You can add multiple groups to your API.

The path is the path to the group. For example, if you have a group with the path /user, the url to access that group would be https://example.com/api/v1/user.

const userGroup = new Group({
  name: 'User Endpoints',
  path: '/user',
});

// Add routes and endpoints to the group ...

v1.addGroup(userGroup);

Add a route to the group

To add a route to your API, use the addRoute function. This function takes a Route object. The Route class is used to create a route for your API. You can add multiple routes to your API.

The path is the path to the route. For example, if you have a route with the path /auth, the url to access that route would be https://example.com/api/v1/user/auth.

const authRoute = new Route({
  name: 'User Authentication Endpoints',
  description: 'Endpoints for user authentication',
  path: '/auth',
});

// Add endpoints to the route ...

userGroup.addRoute(authRoute);

Add an endpoint to the route

To add an endpoint to your API, use the addEndpoint function. This function takes an Endpoint object. The Endpoint class is used to create an endpoint for your API. You can add multiple endpoints to your API.

The path is the path to the endpoint. For example, if you have an endpoint with the path /login, the url to access that endpoint would be https://example.com/api/v1/user/auth/login.

const loginEndpoint = new Endpoint({
  name: 'Login',
  description: 'Login to your account',
  path: '/login',
  method: 'POST',
  controller: (req, res) => {
    res.json({ user: req.user });
  },
});

authRoute.addEndpoint(loginEndpoint);

Generate a Next.js Documentation Site

This will build a static next.js site to the specified output folder in your project directory.

> npx gensite

Export the API to a JSON File

This will export the API to a api.json file in the specified output folder in your project directory.

> npx export-api

Create a basic express-custom project

This will create a basic express-custom project in the current directory, much like npx create-next-app would for a next.js app.

> npx create-api

MDX Documentation

You can create MDX files to document further details about your API. These files will be rendered and displayed on the next.js documentation site.

Custom documentation stays the same for every API version.

Configuration

Create a express-custom.json file in your project directory or add an "express-custom" section to your package.json file to configure the library.

Example express-custom.json:

{
  "file": "src/index.ts",
  "output": "docs",
  "name": "My API",
  "description": "My API description",
  "logo": "https://example.com/logo.png",
  "customDocs": [
    {
      "category": "Welcome",
      "slug": "welcome",
      "basePath": "./custom-docs",
      "files": ["getting-started"]
    }
  ]
  "theme": "default",
  "socials": {
    "github": "https://github.com/slekup/express-custom"
  }
}

`file` (required)

string

The file the API instance is exported from.

This must be a relative path to the file from the project directory. The default export of this file must be an instance of the Api class.

`output`

string

The output directory for the next.js documentation site.

Defaults to docs.

`name`

string

The name of the API.

This will be used as the title of the next.js documentation site. Defaults to API Documentation.

If provided, this must be inbetween 1 and 25 characters.

`description`

string

The description of your API.

`logo`

string

The logo of your API. This will be used as the logo of the next.js documentation site. This must be a url to an image.

Defaults to the Express Custom logo.

`customDocs`

string

An array of objects containing the category, slug, basePath, and files.

category - The name of the category.
slug - The slug to be used in the url.
basePath - The base path (directory) to the MDX files.
files - An array of file names.

{
  "customDocs": [
    {
      "category": "Welcome",
      "slug": "welcome",
      "basePath": "./custom-docs",
      "files": ["getting-started"]
    }
  ]
}

Each file must be an MDX file, but defining the extension in the config is optional. See MDX Documentation.