Developer Documentation

Everything you need to get started with our platform. From installation to deployment, we've got you covered.

Getting Started

Welcome to the Acme SDK! This guide will help you set up your development environment and create your first project in just a few minutes.

Prerequisites

Node.js 18.0 or later
npm, yarn, or pnpm package manager
An Acme account with API access

Before you begin, make sure you have Node.js installed on your machine. You can verify your installation by running node --version in your terminal.

Installation

Install the Acme SDK using your preferred package manager. We recommend using pnpm for faster installation times and efficient disk usage.

Terminal — pnpm

$pnpm add @acme/sdk

Create a New Project

The fastest way to get started is using our CLI to scaffold a new project:

Terminal

# Create a new Acme project

$npx create-acme-app my-project

Creating a new Acme app in /Users/dev/my-project... Installing dependencies: - @acme/sdk - @acme/ui - typescript ✓ Dependencies installed successfully! ✓ Project initialized! Next steps: cd my-project npm run dev

Terminal

# Navigate to your project and start development

$cd my-project

$pnpm dev

▲ Next.js 15.0.0 - Local: http://localhost:3000 - Network: http://192.168.1.100:3000 ✓ Ready in 1.2s

Configuration

Configure your Acme SDK by creating a configuration file in the root of your project. This file controls SDK behavior, API endpoints, and feature flags.

Configuration File

Create an acme.config.ts file in your project root:

acme.config.ts

1import { defineConfig } from '@acme/sdk';
2 
3export default defineConfig({
4  // Your API key from the Acme dashboard
5  apiKey: process.env.ACME_API_KEY,
6 
7  // Environment configuration
8  environment: process.env.NODE_ENV === 'production'
9    ? 'production'
10    : 'development',
11 
12  // Feature flags
13  features: {
14    analytics: true,
15    realtime: true,
16    caching: true,
17  },
18 
19  // API configuration
20  api: {
21    baseUrl: 'https://api.acme.dev',
22    timeout: 30000,
23    retries: 3,
24  },
25});

Environment Variables

Create a .env.local file to store your sensitive configuration:

.env.local

1# Acme SDK Configuration
2ACME_API_KEY=your_api_key_here
3ACME_SECRET_KEY=your_secret_key_here
4 
5# Optional: Override API endpoint
6ACME_API_URL=https://api.acme.dev
7 
8# Database (if using Acme DB)
9DATABASE_URL=postgresql://user:password@localhost:5432/mydb

Security Note: Never commit your .env.local file to version control. Add it to your .gitignore to prevent accidental exposure of sensitive credentials.

Authentication

The Acme SDK provides built-in authentication with support for multiple providers including email/password, OAuth, and magic links.

Initialize Authentication

lib/auth.ts

1import { AcmeAuth } from '@acme/sdk';
2 
3// Initialize the auth client
4export const auth = new AcmeAuth({
5  providers: ['email', 'google', 'github'],
6  redirectUrl: '/dashboard',
7  sessionDuration: '7d',
8});
9 
10// Check if user is authenticated
11export async function getSession() {
12  return await auth.getSession();
13}
14 
15// Sign in with email and password
16export async function signIn(email: string, password: string) {
17  return await auth.signIn({ email, password });
18}
19 
20// Sign out the current user
21export async function signOut() {
22  return await auth.signOut();
23}

Protecting Routes

Use the withAuth middleware to protect your API routes and pages:

middleware.ts

1import { withAuth } from '@acme/sdk/middleware';
2 
3export default withAuth({
4  // Routes that require authentication
5  protectedRoutes: ['/dashboard', '/settings', '/api/private'],
6 
7  // Routes that should redirect authenticated users
8  authRoutes: ['/login', '/register'],
9 
10  // Where to redirect unauthenticated users
11  loginUrl: '/login',
12 
13  // Where to redirect authenticated users from auth pages
14  defaultRedirect: '/dashboard',
15});
16 
17export const config = {
18  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
19};

Using Auth in Components

components/user-menu.tsx

1'use client';
2 
3import { useAuth } from '@acme/sdk/react';
4import { Button } from '@/components/ui';
5 
6export function UserMenu() {
7  const { user, signOut, isLoading } = useAuth();
8 
9  if (isLoading) {
10    return <div>Loading...</div>;
11  }
12 
13  if (!user) {
14    return (
15      <Button href="/login" variant="primary">
16        Sign In
17      </Button>
18    );
19  }
20 
21  return (
22    <div className="flex items-center gap-4">
23      <span>Welcome, {user.name}</span>
24      <Button onClick={signOut} variant="outline">
25        Sign Out
26      </Button>
27    </div>
28  );
29}

API Reference

The Acme SDK provides a type-safe API client for interacting with your backend services. All methods return typed responses and handle errors gracefully.

Making API Calls

lib/api.ts

1import { createClient } from '@acme/sdk';
2 
3// Create an API client instance
4const client = createClient({
5  baseUrl: process.env.ACME_API_URL,
6  headers: {
7    'Authorization': `Bearer ${process.env.ACME_API_KEY}`,
8  },
9});
10 
11// Fetch all users
12export async function getUsers() {
13  const { data, error } = await client.from('users').select('*');
14 
15  if (error) throw error;
16  return data;
17}
18 
19// Fetch a single user by ID
20export async function getUser(id: string) {
21  const { data, error } = await client
22    .from('users')
23    .select('*')
24    .eq('id', id)
25    .single();
26 
27  if (error) throw error;
28  return data;
29}
30 
31// Create a new user
32export async function createUser(user: CreateUserInput) {
33  const { data, error } = await client
34    .from('users')
35    .insert(user)
36    .select()
37    .single();
38 
39  if (error) throw error;
40  return data;
41}
42 
43// Update a user
44export async function updateUser(id: string, updates: UpdateUserInput) {
45  const { data, error } = await client
46    .from('users')
47    .update(updates)
48    .eq('id', id)
49    .select()
50    .single();
51 
52  if (error) throw error;
53  return data;
54}
55 
56// Delete a user
57export async function deleteUser(id: string) {
58  const { error } = await client
59    .from('users')
60    .delete()
61    .eq('id', id);
62 
63  if (error) throw error;
64}

Type Definitions

types/user.ts

1// User type definition
2export interface User {
3  id: string;
4  email: string;
5  name: string;
6  avatar?: string;
7  role: 'admin' | 'user' | 'guest';
8  createdAt: Date;
9  updatedAt: Date;
10}
11 
12// Input types for mutations
13export interface CreateUserInput {
14  email: string;
15  name: string;
16  password: string;
17  role?: User['role'];
18}
19 
20export interface UpdateUserInput {
21  email?: string;
22  name?: string;
23  avatar?: string;
24  role?: User['role'];
25}

Deployment

Deploy your Acme application to production with confidence. We support all major hosting platforms including Vercel, Netlify, and AWS.

Deploy to Vercel

The easiest way to deploy is with Vercel, which provides automatic deployments, preview environments, and seamless integration with Git.

Terminal

# Install Vercel CLI globally

$pnpm add -g vercel

$vercel login

Vercel CLI 32.0.0 > Log in to Vercel ? Log in with: GitHub > Success! GitHub authentication complete.

Terminal

# Deploy to production

$vercel --prod

Vercel CLI 32.0.0 🔍 Inspect: https://vercel.com/acme/my-project/abc123 ✅ Production: https://my-project.vercel.app [2s]

Environment Variables

Make sure to configure your environment variables in your hosting platform's dashboard:

Terminal

# Add environment variables via CLI

$vercel env add ACME_API_KEY

? What's the value of ACME_API_KEY? [hidden] ? Add ACME_API_KEY to which Environments? Production, Preview, Development ✅ Added Environment Variable ACME_API_KEY to Project my-project

Docker Deployment

For self-hosted deployments, use our official Docker image:

Dockerfile

1FROM node:20-alpine AS base
2 
3# Install dependencies only when needed
4FROM base AS deps
5RUN apk add --no-cache libc6-compat
6WORKDIR /app
7 
8COPY package.json pnpm-lock.yaml ./
9RUN corepack enable pnpm && pnpm install --frozen-lockfile
10 
11# Rebuild the source code only when needed
12FROM base AS builder
13WORKDIR /app
14COPY --from=deps /app/node_modules ./node_modules
15COPY . .
16 
17ENV NEXT_TELEMETRY_DISABLED 1
18RUN corepack enable pnpm && pnpm build
19 
20# Production image
21FROM base AS runner
22WORKDIR /app
23 
24ENV NODE_ENV production
25ENV NEXT_TELEMETRY_DISABLED 1
26 
27RUN addgroup --system --gid 1001 nodejs
28RUN adduser --system --uid 1001 nextjs
29 
30COPY --from=builder /app/public ./public
31COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
32COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
33 
34USER nextjs
35 
36EXPOSE 3000
37ENV PORT 3000
38 
39CMD ["node", "server.js"]

Terminal

# Build and run Docker container

$docker build -t my-acme-app .

$docker run -p 3000:3000 --env-file .env.local my-acme-app

▲ Next.js 15.0.0 - Local: http://localhost:3000 ✓ Ready in 892ms

Need Help?

Can't find what you're looking for? Our support team is here to help.

Join Discord CommunityGitHub DiscussionsContact Support