Installation

This page prepares everything StarkForge needs: Node.js, a MongoDB database and a small TypeScript project. It ends with a check that proves the installation works. Plan on about 10 minutes.

Requirements

Everything else is optional and belongs to one feature. Cloudinary stores uploads, Resend sends email, and Google or GitHub apps add social sign-in to Authentication. Each of those pages tells you what to create when you reach it.

Create the Project

Make a folder, create a package.json and install the packages:

mkdir acme-api
cd acme-api
npm init -y
npm install @starklabs/forge zod
npm install --save-dev typescript tsx @types/node

With pnpm, Yarn or Bun, run pnpm add, yarn add or bun add with the same package names. The last three packages are development dependencies.

Set Up package.json

Open package.json, add "type": "module" and replace scripts with the three scripts below. Keep the other keys that npm generated.

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch --env-file=.env src/server.ts",
    "build": "tsc",
    "start": "node --env-file=.env dist/server.js"
  }
}

StarkForge is published as an ES module only, so you load it with import. The "type": "module" key makes Node.js read your own files the same way, and it allows the top-level await that the examples use.

The flag --env-file=.env loads the variables of a file named .env into process.env before your code starts. StarkForge reads no environment variables itself. Your code reads them and passes the values to new Forge, as Environment Variables shows. The flag needs Node.js 20.6 or newer, and the file must exist, so create an empty file named .env next to package.json now, in your editor or with touch .env.

Configure TypeScript

Create tsconfig.json next to package.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"],
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

NodeNext has one effect on your own code: a relative import ends in .js even though the file is a .ts file, for example ./collections/products.js. The Project Structure page shows where this matters.

Get a MongoDB Database

StarkForge stores data in MongoDB. Choose one of the three options below. In development, when you give no connection string, StarkForge connects to mongodb://127.0.0.1:27017, which is a MongoDB server on your own machine at its default port.

Run MongoDB With Docker

docker run -d --name acme-mongo -p 27017:27017 mongo:8

Stop it with docker stop acme-mongo and start it again with docker start acme-mongo.

Install MongoDB Locally

Follow the MongoDB installation guide for your system and start the mongod service. It listens on port 27017 by default.

Use MongoDB Atlas

Create a free cluster on MongoDB Atlas, copy its connection string and save it in .env as MONGODB_URI. Your code then passes it to StarkForge as mongoDBURI: process.env.MONGODB_URI. Atlas only accepts connections from addresses on its network access list, so add your own address there first.

When MongoDB Is Not Running

If StarkForge cannot reach the database, forge.start() waits about 10 seconds and then fails with status 503 and the code DATABASE_UNAVAILABLE. These are the important lines of the terminal output:

ServiceUnavailableError: Could not connect to MongoDB.
  statusCode: 503,
  code: 'DATABASE_UNAVAILABLE',
  hint: "Check 'mongoDBURI' and that the database accepts connections from this machine.",
  [cause]: MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

ECONNREFUSED means that nothing is listening at that address. Start MongoDB, or correct the connection string.

JavaScript Instead of TypeScript

TypeScript is optional. The examples in this documentation are TypeScript without type annotations, so they run as JavaScript when you rename the files from .ts to .js. In a JavaScript project you skip typescript, tsx, @types/node and tsconfig.json, keep "type": "module", and let Node.js run the files directly:

{
  "type": "module",
  "scripts": {
    "dev": "node --watch --env-file=.env src/server.js",
    "start": "node --env-file=.env src/server.js"
  }
}

Check the Installation

First run a script that needs no database. It creates a Forge, which validates the default configuration, and prints two values from it:

// src/check.ts
import { Forge } from "@starklabs/forge";

const forge = new Forge();
console.log(`Environment: ${forge.config.env}`);
console.log(`API prefix: ${forge.config.apiPrefix}`);

npx tsx src/check.ts

Environment: development
API prefix: /api/v1

If you see these two lines, the package is installed and TypeScript runs your files. Next, start a real server. With MongoDB running, create the smallest StarkForge program:

// src/server.ts
import { Forge } from "@starklabs/forge";

const forge = new Forge();
await forge.start();

npm run dev

In a second terminal, call the health route:

curl http://localhost:5000/api/v1/health

The answer contains "status": "ok" and "database": "up". Stop the server with Ctrl + C.

Fix Common Problems

Where to Go Next

:::