{"id":12830,"library":"arkos","title":"Arkos Framework","description":"Arkos is a TypeScript-first RESTful framework built on Express and designed to automate API route generation for common CRUD operations, particularly with Prisma. It provides an auto-routing system, comprehensive authentication and authorization features (introducing a new ArkosPolicy API since v1.6-canary.48), an email service, robust error handling, and file upload capabilities with image optimization. While initially tightly coupled with Prisma, releases from v1.5.9-beta onwards made Prisma integration optional; the framework can now operate without an active Prisma instance, gracefully skipping Prisma-dependent features while emitting a warning. The project is under active development, evidenced by its current `1.5.9-beta` stable version and frequent `canary` and `next` releases, indicating a rapid cadence for feature additions and improvements. It aims to offer an opinionated, highly customizable solution for building scalable APIs.","status":"active","version":"1.5.9-beta","language":"javascript","source_language":"en","source_url":"https://github.com/uanela/arkos","tags":["javascript","auto API routes","TypeScript package","API generator","authentication","email service","error handling","file upload","image optimization","typescript"],"install":[{"cmd":"npm install arkos","lang":"bash","label":"npm"},{"cmd":"yarn add arkos","lang":"bash","label":"yarn"},{"cmd":"pnpm add arkos","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core web server framework, Arkos builds on it.","package":"express","optional":false},{"reason":"ORM integration for database interactions, optional since v1.5.9-beta.","package":"@prisma/client","optional":true},{"reason":"Schema validation library for request and response data.","package":"zod","optional":false},{"reason":"Middleware for handling `multipart/form-data` for file uploads.","package":"multer","optional":false},{"reason":"Used for JWT-based authentication.","package":"jsonwebtoken","optional":false},{"reason":"Used for password hashing and comparison in authentication.","package":"bcryptjs","optional":false},{"reason":"Email service integration for sending emails.","package":"nodemailer","optional":false},{"reason":"Express middleware for enabling Cross-Origin Resource Sharing.","package":"cors","optional":false},{"reason":"Image processing library, used for optimization with file uploads.","package":"sharp","optional":false},{"reason":"Configuration management for environment variables.","package":"dotenv","optional":false},{"reason":"Used for object validation.","package":"class-validator","optional":false},{"reason":"Used for transforming plain objects to class instances and vice-versa.","package":"class-transformer","optional":false},{"reason":"Middleware for limiting repeated requests to public APIs.","package":"express-rate-limit","optional":false}],"imports":[{"note":"The primary function for initializing the Arkos application. Arkos is primarily designed for ESM projects.","wrong":"const { createArkosApp } = require('arkos')","symbol":"createArkosApp","correct":"import { createArkosApp } from 'arkos'"},{"note":"New fluent API for defining authorization policies, introduced in v1.6.0-canary.48, replacing older `.auth.ts` files.","wrong":"const { ArkosPolicy } = require('arkos')","symbol":"ArkosPolicy","correct":"import { ArkosPolicy } from 'arkos'"},{"note":"Utility class for custom application errors. Error handling shape changed significantly in v1.6.0-canary.52.","wrong":"const { AppError } = require('arkos')","symbol":"AppError","correct":"import { AppError } from 'arkos'"}],"quickstart":{"code":"import { createArkosApp } from 'arkos';\nimport express from 'express';\nimport dotenv from 'dotenv';\n\ndotenv.config();\n\nconst app = express();\n\nconst arkos = createArkosApp(app, {\n  // Pass your PrismaClient instance here if you are using Prisma.\n  // If omitted, Arkos will operate in a Prisma-optional mode.\n  // prisma: new PrismaClient(), \n  env: process.env.NODE_ENV ?? 'development',\n  port: parseInt(process.env.PORT ?? '3000'),\n  // Further configurations like email, authentication, etc.\n});\n\n// Add custom Express routes before Arkos starts listening\napp.get('/health', (req, res) => {\n  res.status(200).json({ status: 'ok', framework: 'arkos', version: arkos.config.env });\n});\n\n// Start the Arkos application, which also starts the underlying Express server\narkos.listen().then(() => {\n  console.log(`Arkos server listening on port ${arkos.config.port}`);\n  console.log(`OpenAPI documentation available at /api-docs`);\n}).catch(error => {\n  console.error('Failed to start Arkos server:', error);\n  process.exit(1);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Refactor 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.","message":"The 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`.","severity":"breaking","affected_versions":">=1.6.0-canary.52"},{"fix":"Update any frontend or backend logic that parses or displays these specific error messages to reflect the new, concise formats.","message":"Unique 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'.","severity":"breaking","affected_versions":">=1.6.0-canary.52"},{"fix":"Rename all instances of `RouterConfig` to `RouteHook` in your application to avoid future breaking changes.","message":"The `RouterConfig` API has been renamed to `RouteHook`. While `RouterConfig` may still work with a deprecation warning for a short period, it will be removed.","severity":"breaking","affected_versions":">=1.6.0-canary.48"},{"fix":"Migrate your authentication and authorization logic from `.auth.ts` files to the new fluent `ArkosPolicy` interface for defining rules.","message":"The `ArkosPolicy` API (v1.6) for defining permissions was introduced, replacing the older, scattered `.auth.ts` files.","severity":"breaking","affected_versions":">=1.6.0-canary.48"},{"fix":"If 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.","message":"Arkos 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).","severity":"gotcha","affected_versions":">=1.5.9-beta"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install 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`.","cause":"Arkos relies on several peer dependencies (like 'express', '@prisma/client', 'zod', 'multer') that must be explicitly installed in your project.","error":"Error: Cannot find module 'express' from 'arkos'"},{"error":"TypeError: Arkos is not a constructor"},{"error":"SyntaxError: require() of ES Module ... not supported. Instead, change the require of ... to a dynamic import() which is available in all CommonJS modules."},{"fix":"Ensure 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.","cause":"Attempting to use CommonJS `require()` syntax or an incorrect instantiation method for Arkos, which is designed as an ES Module.","error":"TypeError: The 'this' context of 'createArkosApp' must be a 'ArkosApp' instance."},{"fix":"Verify 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.","cause":"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.","error":"PrismaClientInitializationError: Invalid URL or connection string provided for your database."},{"fix":"Migrate 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`.","cause":"Using the old `.auth.ts` pattern or outdated policy definition after the introduction of the `ArkosPolicy` API v1.6.","error":"Property 'auth' does not exist on type 'PostPolicy'. Did you mean 'rules'?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}