Installation

On this guide you will learn how to install and create an Arkos.js project.

System Requirements

Before you begin, make sure your system meets the following requirements:

• Node.js 22.9 or later
• macOS, Windows, or Linux

Quick Start

The quickest way to create a new Arkos.js RESTful API is using create-arkos, which sets up everything automatically for you.

1. Run create-arkos

pnpm create arkos@latest

npm create arkos@latest

On installation, you'll see the following prompts:

? What is the name of your project? my-project
? Would you like to use TypeScript? Yes
? What db provider will be used for Prisma? postgresql
? Would you like to set up Validation? Yes
? Choose validation library: zod
? Would you like to set up Authentication? Yes
? Choose authentication type: static
? Choose default username field for login: email
? Would you like to use authentication with Multiple Roles? Yes

After the prompts, create-arkos will create a folder with your project name, install all required dependencies, and run npx prisma generate to generate your first @prisma/client.

2. Setup Environment Variables

Add DATABASE_URL and JWT_SECRET to the .env file that was generated:

DATABASE_URL=postgresql://username:password@localhost:5432/my-project
JWT_SECRET=my-super-secret-key
PORT=8000

3. Initialize Database

Once your DATABASE_URL is set, initialize your database with Prisma:

npx prisma db push

Or if you prefer migrations:

npx prisma migrate dev --name init

4. Generate Arkos and Prisma Client Types

npx arkos prisma generate

5. Run The Dev Server

After these steps you're ready to start developing.

pnpm run dev

npm run dev

Your application will be running at http://localhost:8000/api or on the PORT you set in .env.

Manual Installation

1. Initialize Your Project

mkdir my-arkos-project
cd my-arkos-project
pnpm init

2. Install Required Packages

pnpm add arkos @prisma/client
pnpm add -D typescript @types/node prisma tsx-strict

pnpm add arkos @prisma/client
pnpm add -D prisma tsx-strict

3. Configure Environment Variables

Create your .env file:

DATABASE_URL=your-database-connection-string
JWT_SECRET=your-secret-key-for-authentication
PORT=8000

4. Set Up Prisma Schema

Create prisma/schema.prisma:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql" // or mysql, mongodb, sqlite, etc.
  url      = env("DATABASE_URL")
}

5. Export Your Prisma Client

Arkos requires your Prisma client to be exported as default from src/utils/prisma/index.ts so it can dynamically import it to manage auto-generated endpoints and power the BaseService class.

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

export default prisma;

6. Configure Your Application

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    cors: {
      allowedOrigins: "*",
    },
  },
});

import arkos from "arkos";

const app = arkos();

app.listen();

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    cors: {
      allowedOrigins: "*",
    },
  },
};

export default arkosConfig;

import arkos from "arkos";

arkos.init();

import arkos from "arkos";

arkos.init({
  middlewares: {
    cors: {
      allowedOrigins: "*",
    },
  },
});

7. Set Up Package.json Scripts

{
  "type": "module",
  "scripts": {
    "dev": "arkos dev",
    "build": "arkos build",
    "start": "arkos start",
    "arkos": "arkos"
  },
  "prisma": {
    "schema": "prisma/schema/"
  }
}

• dev — Starts the development server with hot reloading
• build — Builds your application for production
• start — Runs the built application in production mode
• arkos — Provides access to Arkos CLI commands

8. Initialize Database

npx prisma generate
npx prisma db push

9. Generate Arkos and Prisma Client Types

npx arkos prisma generate

10. Start Development Server

pnpm run dev

npm run dev

Your API is now running at http://localhost:8000/api. From here, refer to Project Structure to understand how to organize your code, and Configuration for all available options.