Arkos.js - The Express And Prisma RESTful Framework

When Arkos boots, it reads your Prisma schema, authentication configuration, and file upload configuration to automatically register three categories of routes — Prisma Model Routes, Authentication Routes, and File Upload Routes. No route definitions needed. Every endpoint that comes from these categories is fully functional out of the box, and every one of them can be intercepted, configured, or disabled without touching Arkos internals.

How It Works

At boot time, Arkos scans your project and registers routes in this order:

Built-in Arkos middleware (body parser, CORS, etc.)
Your own routers and middleware

Registered via app.use() before app.listen()

Registered via arkos.init({ use: [] })

Auto-generated routes (model, authentication, file upload)

This means your custom routes always take precedence over generated ones.

Configuring Generated Routes with Route Hook

Every generated route accepts the same configuration object used in ArkosRouter. You control this through a hook export from the module's router file.

RouteHook is the new name for export const config: RouterConfig introduced in v1.6. The old name still works but will log a deprecation warning. See Route Hook for the full guide.

For a Prisma model, that file lives at src/modules/<model>/<model>.router.ts. For authentication and file uploads, Arkos looks for src/modules/auth/auth.router.ts and src/modules/file-upload/file-upload.router.ts respectively.

Prisma Model Route Hook

src/modules/post/post.router.ts

import { ArkosRouter, RouteHook } from "arkos";
import postPolicy from "@/src/modules/post/post.policy";
import { UpdatePostSchema } from "@/src/modules/post/post.schema";

export const hook: RouteHook = {
  findMany: { authentication: false },
  findOne: { authentication: true },
  createOne: { authentication: postPolicy.Create },
  updateOne: {
    authentication: postPolicy.Update,
    validation: { body: UpdatePostSchema },
  },
  deleteOne: { authentication: postPolicy.Delete },
  createMany: { disabled: true },
  updateMany: { disabled: true },
  deleteMany: { disabled: true },
};

const router = ArkosRouter();

export default router;

Authentication Route Hook

src/modules/auth/auth.router.ts

import { ArkosRouter, RouteHook } from "arkos";
import { UpdateMeSchema } from "@/src/modules/auth/auth.schema";

export const hook: RouteHook = {
  login: { rateLimit: { windowMs: 15 * 60_000, max: 10 } },
  signup: { disabled: true },
  getMe: { rateLimit: { windowMs: 15 * 60_000, max: 30 } },
  deleteMe: { disabled: true },
  updateMe: { validation: { body: UpdateMeSchema } },
};

const router = ArkosRouter();

export default router;

File Upload Route Hook

src/modules/file-upload/file-upload.router.ts

import { ArkosRouter, RouteHook } from "arkos";

export const hook: RouteHook = {
  findFile: { authentication: false },
  uploadFile: { authentication: true },
  updateFile: { authentication: true },
  deleteFile: { disabled: true },
};

const router = ArkosRouter();

export default router;

The router file must export hook as a named export and the router instance as the default export. If either convention is not followed, Arkos won't pick up your customizations.

You can also add your own endpoints to any of these router files — they'll be mounted under the same base path as the generated routes for that module.

Intercepting Generated Routes

Every generated endpoint can be intercepted — run logic before or after any operation without replacing the built-in behavior. Arkos looks for an interceptors file next to the router file:

src/modules/post/post.interceptors.ts

import { ArkosRequest, ArkosResponse, ArkosNextFunction } from "arkos";

export const afterCreateOne = [
  async (req: ArkosRequest, res: ArkosResponse, next: ArkosNextFunction) => {
    console.log("Post created:", res.locals.data);
    next();
  },
];

The same convention applies to auth and file upload interceptors — the file lives at auth.interceptors.ts or file-upload.interceptors.ts with the corresponding hook names (afterLogin, beforeUploadFile, etc.).

See Interceptors for the full list of available hooks per category.

The Three Categories

Prisma Model Routes — RESTful endpoints generated from your Prisma schema, with built-in filtering, sorting, pagination, field selection, and full-text search.
Authentication Routes — Login, signup, logout, password update, and current user endpoints.
File Upload Routes — Upload, replace, retrieve, and delete endpoints for standalone file operations.

Generated Routes