Quick Start
Get Scrawn up and running in minutes
Get Scrawn backend and SDK running in your project. This guide will walk you through setting up the backend, configuring your database, and integrating the SDK.
1. Clone the Repository
git clone https://github.com/ScrawnDotDev/Scrawn.git
cd Scrawngh repo clone ScrawnDotDev/Scrawn
cd Scrawn1.1 Install packages
bun installnpm installyarn install2. Configure User ID Type
Open src/config/identifiers.ts and set your user ID type based on your database schema:
// Choose the ID type that matches your database
export const USER_ID_CONFIG = ID_CONFIGS.uuid;
export const USER_ID_CONFIG = ID_CONFIGS.uuid; // For UUID user IDs
// export const USER_ID_CONFIG = ID_CONFIGS.bigint; // For BigInt user IDs
// export const USER_ID_CONFIG = ID_CONFIGS.int; // For Integer user IDs3. Setup Environment Variables
Copy the example environment file to create your local configuration:
cp .env.example .env.localcopy .env.example .env.localCopy-Item .env.example .env.localNow edit .env.local with your configuration:
HMAC_SECRET="YOUR_VERY_SECRET_CODE_GOES_HERE"
DATABASE_URL="YOUR_NOT_SO_SECRET_DATABASE_URL_GOES_HERE"
LEMON_SQUEEZY_API_KEY=""
LEMON_SQUEEZY_STORE_ID=""
LEMON_SQUEEZY_VARIANT_ID="" 3.1 Generate HMAC Secret
Generate a secure HMAC secret:
openssl rand -base64 64Copy the output and paste it as your HMAC_SECRET value.
3.2 Database URL
Set up a PostgreSQL database and paste the connection URL. You can use:
Example: postgresql://user:password@host:5432/database
3.3 Lemon Squeezy Configuration
- Sign up at Lemon Squeezy
- Follow their Getting Started Guide
- Get your API key, Store ID, and Variant ID from the dashboard
4. Run Database Migrations
drizzle-kit push5. Generate Initial API Key
bun run init_keynpm run init_keyyarn run init_keyYou'll see output like this:
=== Initial API Key Generated ===
API Key Details:
ID: 0f3f5bb5-6552-4124-9419-eb4d9e965c4f
Key: scrn_ezjTCI05kThwRiaecXniaBVptqHSnvv0
Name: Dashboard Key
Created At: 2025-11-15T09:07:58.380Z
Expires At: 2026-11-15T09:07:58.380Z
=== SQL INSERT Statement ===
INSERT INTO api_keys (id, name, key, created_at, expires_at, revoked, revoked_at)
VALUES (
'0f3f5bb5-6552-4124-9419-eb4d9e965c4f',
'Dashboard Key',
'32dee4c664e35901e4d1a89b34ddace0f8fbcdde058c9550b28b918835a4b3c0',
'2025-11-15T09:07:58.380Z',
'2026-11-15T09:07:58.380Z',
false,
NULL
);
=== Usage ===
Authorization: Bearer scrn_ezjTCI05kThwRiaecXniaBVptqHSnvv0
=== IMPORTANT ===
1. The key is stored as an HMAC-SHA256 hash in the database
2. Run the SQL INSERT statement above in your PostgreSQL database
3. Use the PLAINTEXT API key (above) in the Authorization header
4. Keep this API key secure - it will be used to generate new API keys
5. The plaintext key is shown only once - save it now!
=================Important
Save this API key now! You can use it directly with the SDK, but we recommend setting up the dashboard first and using it to generate separate keys for production use.
See the Dashboard Setup Guide for details.
5.1 Run the SQL Insert
Copy the SQL INSERT statement from the output and run it in your database provider's SQL editor (Supabase SQL Editor, Neon Console, etc.).
6. Deploy Scrawn Backend
Your backend is now configured! Deploy it to your preferred platform:
Local Testing
For easy local testing, refer local running guide.
7. Install SDK in Your Project
Now integrate Scrawn into your application:
bun add @scrawn/corenpm install @scrawn/coreyarn add @scrawn/coreEnjoy! 🎉
Start tracking usage and billing your customers:
import { Scrawn } from '@scrawn/core';
const scrawn = new Scrawn({
apiKey: process.env.SCRAWN_KEY,
baseURL: process.env.SCRAWN_BASE_URL,
});
// Track usage
await scrawn.sdkCallEventConsumer({
userId: '0a1e38a5-e2f3-450f-9796-59ad406d93dc',
debitAmount: 5000,
});
Configuration
API Key: Use the key you generated in Step 5 or get one from your Dashboard.
Base URL: Use the URL you get after deploying your Scrawn backend.
Next Steps
Dive deeper into Scrawn's capabilities: