Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createArkosApp
✓ import { createArkosApp } from 'arkos'
✗ const { createArkosApp } = require('arkos')
The primary function for initializing the Arkos application. Arkos is primarily designed for ESM projects.
ArkosPolicy
✓ import { ArkosPolicy } from 'arkos'
✗ const { ArkosPolicy } = require('arkos')
New fluent API for defining authorization policies, introduced in v1.6.0-canary.48, replacing older `.auth.ts` files.
AppError
✓ import { AppError } from 'arkos'
✗ const { AppError } = require('arkos')
Utility class for custom application errors. Error handling shape changed significantly in v1.6.0-canary.52.
This quickstart initializes a basic Arkos application, configures it with environment variables, adds a custom Express health check route, and starts the server. It demonstrates the `createArkosApp` entry point.
import { createArkosApp } from 'arkos';
import express from 'express';
import dotenv from 'dotenv';
dotenv.config();
const app = express();
const arkos = createArkosApp(app, {
// Pass your PrismaClient instance here if you are using Prisma.
// If omitted, Arkos will operate in a Prisma-optional mode.
// prisma: new PrismaClient(),
env: process.env.NODE_ENV ?? 'development',
port: parseInt(process.env.PORT ?? '3000'),
// Further configurations like email, authentication, etc.
});
// Add custom Express routes before Arkos starts listening
app.get('/health', (req, res) => {
res.status(200).json({ status: 'ok', framework: 'arkos', version: arkos.config.env });
});
// Start the Arkos application, which also starts the underlying Express server
arkos.listen().then(() => {
console.log(`Arkos server listening on port ${arkos.config.port}`);
console.log(`OpenAPI documentation available at /api-docs`);
}).catch(error => {
console.error('Failed to start Arkos server:', error);
process.exit(1);
});
Debug
Known issues
breakingThe error handling mechanism has been significantly simplified. `sendDevelopmentError` and `sendProductionError` no longer differentiate between `/api` and non-API routes. All errors now conform to a single, unified response shape, and the `missing` flag has been removed from `AppError`.fixRefactor custom error handling logic to align with the new unified error response structure. Ensure any reliance on the `missing` flag or differentiated error responses is removed.
affects: >=1.6.0-canary.52
breakingUnique constraint error messages from Prisma have been shortened (e.g., 'Duplicate unique field(s) 'email'') and Prisma validation error messages have changed to 'Invalid query arguments'.fixUpdate any frontend or backend logic that parses or displays these specific error messages to reflect the new, concise formats.
affects: >=1.6.0-canary.52
breakingThe `RouterConfig` API has been renamed to `RouteHook`. While `RouterConfig` may still work with a deprecation warning for a short period, it will be removed.fixRename all instances of `RouterConfig` to `RouteHook` in your application to avoid future breaking changes.
affects: >=1.6.0-canary.48
breakingThe `ArkosPolicy` API (v1.6) for defining permissions was introduced, replacing the older, scattered `.auth.ts` files.fixMigrate your authentication and authorization logic from `.auth.ts` files to the new fluent `ArkosPolicy` interface for defining rules.
affects: >=1.6.0-canary.48
gotchaArkos now supports a Prisma-optional architecture since v1.5.9-beta. If a PrismaClient instance is not provided to `createArkosApp`, the framework will emit a warning and gracefully skip all Prisma-dependent features (e.g., Auth routes, CRUD router setup).fixIf your application relies on Prisma-backed features, ensure you explicitly pass `prisma: new PrismaClient()` to the `createArkosApp` configuration. If you intend to use Arkos without Prisma, be aware that certain features will be unavailable.
affects: >=1.5.9-beta
Errors
Common errors & fixes
Error: Cannot find module 'express' from 'arkos'
Arkos relies on several peer dependencies (like 'express', '@prisma/client', 'zod', 'multer') that must be explicitly installed in your project.
fixInstall all required peer dependencies using npm or yarn, e.g., `npm install express @prisma/client zod cors sharp dotenv multer bcryptjs mimetype nodemailer compression html-to-text jsonwebtoken cookie-parser dotenv-expand swagger-jsdoc class-validator class-transformer express-rate-limit zod-to-json-schema class-validator-jsonschema @scalar/express-api-reference`.
TypeError: Arkos is not a constructor
SyntaxError: require() of ES Module ... not supported. Instead, change the require of ... to a dynamic import() which is available in all CommonJS modules.
TypeError: The 'this' context of 'createArkosApp' must be a 'ArkosApp' instance.
Attempting to use CommonJS `require()` syntax or an incorrect instantiation method for Arkos, which is designed as an ES Module.
fixEnsure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and use `import { createArkosApp } from 'arkos';` syntax for all Arkos imports. PrismaClientInitializationError: Invalid URL or connection string provided for your database.
The Prisma Client could not connect to the database, often due to an incorrect database URL in `.env` or the database server being unreachable, or Arkos is attempting to use Prisma features without a proper PrismaClient instance.
fixVerify your `DATABASE_URL` in your `.env` file is correct and accessible. Ensure your database server is running. If you intend to use Prisma with Arkos, pass `prisma: new PrismaClient()` to the `createArkosApp` configuration.
Property 'auth' does not exist on type 'PostPolicy'. Did you mean 'rules'?
Using the old `.auth.ts` pattern or outdated policy definition after the introduction of the `ArkosPolicy` API v1.6.
fixMigrate your authorization definitions to the new fluent `ArkosPolicy` interface, which uses a `.rule()` chain for defining permissions, as introduced in `v1.6.0-canary.48`.
Audit
Dependencies
expressrequiredCore web server framework, Arkos builds on it.
@prisma/clientoptionalORM integration for database interactions, optional since v1.5.9-beta.
zodrequiredSchema validation library for request and response data.
multerrequiredMiddleware for handling `multipart/form-data` for file uploads.
jsonwebtokenrequiredUsed for JWT-based authentication.
bcryptjsrequiredUsed for password hashing and comparison in authentication.
nodemailerrequiredEmail service integration for sending emails.
corsrequiredExpress middleware for enabling Cross-Origin Resource Sharing.
sharprequiredImage processing library, used for optimization with file uploads.
dotenvrequiredConfiguration management for environment variables.
class-validatorrequiredUsed for object validation.
class-transformerrequiredUsed for transforming plain objects to class instances and vice-versa.
express-rate-limitrequiredMiddleware for limiting repeated requests to public APIs.