Express

@runonatlas/express is our Express.js library for Atlas, which provides all the middleware and backend resources you need.

Installation

npm

Terminal

npm install @runonatlas/express

Initialization

This only covers the backend initialization with Express. You will also need to initialize your frontend. For example, React or Next.js.

Initializing the Atlas SDK is very easy. You just need to follow these steps:

1. Set the Atlas API key in the environment variables

   You can get it from the Atlas Dashboard.

   .env

   ATLAS_API_KEY="INSERT_YOUR_ATLAS_API_KEY"
   

2. Create the Atlas Express Client

   To initialize the Atlas SDK, you need to instantiate the Atlas Client with the following parameters:

   1. Your Atlas API key.
   2. A function that returns the user id given a request object.

   Using Clerk

   When using Clerk, you just need to pass the getAuth function to get the userId.

   src/index.ts

   import { AtlasExpressClient } from "@runonatlas/express";
   import { clerkMiddleware, getAuth } from "@clerk/express";
   import express from "express";
   
   const app = express();
   const atlas = new AtlasExpressClient(
     (req) => getAuth(req).userId
   );
   
   app.use(clerkMiddleware());
   
   app.use("/", atlas.router);
   

Having CORS issues?

If you are having CORS issues only with Atlas, it probably means that your CORS middleware is running after the Atlas server. Make sure to place the CORS middleware before the Atlas server. For example:

src/index.ts

import { AtlasExpressClient } from "@runonatlas/express";
import express from "express";
import { clerkMiddleware, getAuth } from "@clerk/express";
import cors from "cors";
import corsOptions from "./corsOptions";

const app = express();
const atlas = new AtlasExpressClient(
  (req) => getAuth(req).userId
);
app.use(cors(corsOptions));
app.use(clerkMiddleware());

app.use("/", atlas.router);

Restrict user access based on their subscriptions

You can prevent users from accessing restricted parts of your application based on their subscription. To do so, you can use our backend protection features.

Backend Protection

In order to prevent users from using certain endpoints unless they have a plan with the required features, we only need to add a middleware.

app.post(
  "/api/generate-caption",
  atlas.createFeaturesMiddleware(["data-explorer"]), // Add this line
  (req, res) => {
    // Your endpoint logic here
  }
);

This will automatically prevent users who don’t have the data-explorer feature in their active plan from accessing the endpoint.

Remember that you need to have followed the installation guide before you can use any of these features.

Limit-based features

Sometimes, just having a feature as enabled or disabled is not enough, and our pricing models require limits to be set. For example, 5 users per account, or 20GB of storage. Setting this up with Atlas is very easy. And, if at some point the limits change, you won’t need to change the code again!

Configuring the backend

The backend needs to understand what the limits are and how to check if the limit has been reached. To do so, when initializing the Atlas Client, you can provide a limits object with callbacks per each limit that you might want to use.

For example, given a feature whose id is data-explorer, you can provide a callback to check if the limit has been reached:

src/index.ts

import { AtlasExpressClient } from "@runonatlas/express";
import express from "express";
import { getAuth } from "@clerk/express";
import { prisma } from "./db";

const app = express();
const atlas = new AtlasExpressClient(
  (req) => getAuth(req).userId,
  {
    limits: {
      "data-explorer": (userId: string) => prisma.explorations.count({
        where: {
          userId,
        },
      }),
    },
  }
);

// ... Remaining code

Now, every time you the application needs to check if the data-explorer feature is available, Atlas will use the callback to compute it.

What happens if you don't configure a limit?

By default, if you haven’t configured a limit callback, Atlas will deny access to the feature if it has a limit. You can easily override this behavior. For example:

src/index.ts

import { AtlasExpressClient } from "@runonatlas/express";
import express from "express";
import { getAuth } from "@clerk/express";
import { prisma } from "./db";

const app = express();
const atlas = new AtlasExpressClient(
  (req) => getAuth(req).userId,
  {
    baseClientOptions: {
      allowUnknownLimits: true
    },
  }
);

Organizations

This only covers the backend configuration. You will also need to configure your frontend. For example, React or Next.js.

In many applications, it’s common to allow multiple users to belong to the same organization and share a single subscription. For example: Alice creates an organization called Standard Corp, purchases a plan, and invites Bob and Carol to join. Since all three are members of the same organization, they should share access to the same plan and limits.

To enable this, you should use the organization ID as the user identifier instead of the individual user ID. This tells Atlas that access and usage should be scoped to the organization — not the individual — ensuring that Bob and Carol both have access under Standard Corp’s plan.

src/index.ts

import { AtlasExpressClient } from "@runonatlas/express";
import { getAuth } from "@clerk/express";
import express from "express";

const app = express();
const atlas = new AtlasExpressClient(
  (req) => getAuth(req).orgId
);

app.use("/", atlas.router);