Skip to main content

Installation New

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 20.19 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. To create a project, run:

1. Run create-arkos​

pnpm 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 and install all required dependencies and also will run npx prisma generate to generate your first @prisma/client.

2. Setup Environment Variables​

Next steps will be to add DATABASE_URL under .env (which will be generated by create-arkos) and JWT_SECRET which will come with a placeholder:

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

3. Initialize Database​

After you have your DATABASE_URL setup under .env, you then initialize your database with Prisma by running:

npx prisma db push

or if you are using SQL and prefer to create a migration:

npx prisma migrate --init

After following these 3 steps described above, you will be 100% ready to start developing and scaling your RESTful API easily using Arkos.js by running the dev command:

pnpm run dev

By doing this you will have your application running on http://localhost:8000/api or on the PORT you set in your .env file.

Manual Installation​

To manually create a new Arkos.js API, follow these steps:

1. Initialize Your Project​

mkdir my-arkos-project
cd my-arkos-project
npm init -y

2. Install Required Packages​

npm install arkos express @prisma/client 
npm install --save-dev typescript @types/node @types/express prisma tsx-strict

3. Create Project Structure​

tip

In the following examples for file extensions, you will find examples like src/app.js. It's just a matter of changing to src/app.ts if you are using TypeScript.

After installing the required dependencies, you will need to set up the Arkos.js project structure:

  • Create prisma/schema/schema.prisma, which will be set up in Step 5.
  • Create src/app.js, which is the application entry point. Set up at Step 6.
  • Create src/utils/prisma/index.js, your Prisma client, which will be set up in Step 7.

4. Configure Environment Variables​

Edit your .env file:

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

5. Set Up Prisma Schema​

Create prisma/schema.prisma with your database schema:

// Example schema - customize according to your needs
generator client {
  provider = "prisma-client-js"
}

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

6. Configure Your Application​

Edit src/app.js (or src/app.ts for TypeScript):

import arkos from 'arkos';

arkos.init({
  cors: {
    allowedOrigins: process.env.NODE_ENV !== "production" ? "*" : "your-production-url"
  }
});

In the snippet above, we configured CORS so that we can run our application freely during development.

7. Export Your Prisma Client​

Arkos.js requires your Prisma client to be exported as default under src/utils/prisma/index.js (or src/utils/prisma/index.ts for TypeScript) so that it can dynamically import it later to manage your application's auto-generated endpoints and enhance Prisma power through the BaseService Class.

import { PrismaClient } from "@prisma/client"

const prisma = new PrismaClient()

export default prisma

8. Set Up Package.json Scripts​

Edit your package.json to include these scripts:

info

In the following package.json, we have "type": "module". This is only required for JavaScript projects. If you are using TypeScript, you should not include this.

{
  "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 enabled
  • build: Builds your application for production deployment
  • start: Runs the built application in production mode
  • arkos: Provides access to Arkos CLI commands for generating components

9. Initialize Database​

npx prisma generate
npx prisma db push
# or use migrations: npx prisma migrate dev --name init

10. Start Development Server​

pnpm run dev

You can then visit your API at http://localhost:8000/api and start developing and quickly scaling your API using Arkos.js.

If you installed Arkos.js manually, you can reference other parts of the documentation to find out how to set up authentication, validation, auto swagger documentation, and many other features available in Arkos.