notion-deploy-integration

What this skill does

# Deploy Notion-Integrated Applications

Ship Node.js apps that talk to the Notion API to Vercel, Railway, or Fly.io. This skill covers environment variable management, the Notion client singleton pattern for serverless, rate limit handling at 3 req/sec, health check endpoints that verify Notion connectivity, and caching strategies to reduce API calls.

## Prerequisites

- Node.js >= 18 project with `@notionhq/client` installed (`npm i @notionhq/client`)
- Working Notion integration tested locally with a valid `NOTION_TOKEN` (starts with `ntn_`)
- Platform CLI installed for your target: `vercel`, `railway`, or `fly`
- Database or page IDs your integration needs access to

## Instructions

### Step 1 — Prepare the Application for Production

Build a production-ready entry point with a Notion client singleton, rate limit handling, response caching, and a health check endpoint.

**Notion client singleton (critical for serverless):**

Serverless functions recycle containers unpredictably. Creating a new `Client` on every invocation wastes cold-start time and risks hitting rate limits. A module-level singleton reuses the client across warm invocations.

```typescript
// src/notion-client.ts — singleton for serverless environments
import { Client, LogLevel, isNotionClientError, APIErrorCode } from '@notionhq/client';

let client: Client | null = null;

export function getNotionClient(): Client {
  if (!client) {
    if (!process.env.NOTION_TOKEN) {
      throw new Error('NOTION_TOKEN environment variable is not set');
    }
    client = new Client({
      auth: process.env.NOTION_TOKEN,
      logLevel: process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.DEBUG,
      timeoutMs: 30_000,
    });
  }
  return client;
}
```

**Rate limit handler (Notion enforces 3 requests/second):**

Notion returns HTTP 429 with a `Retry-After` header when you exceed the rate limit. The SDK retries automatically, but production apps should add queuing to avoid cascading failures under load.

```typescript
// src/rate-limiter.ts — token bucket for 3 req/sec
export class NotionRateLimiter {
  private queue: Array<{ resolve: () => void }> = [];
  private activeRequests = 0;
  private readonly maxPerSecond = 3;

  async acquire(): Promise<void> {
    if (this.activeRequests < this.maxPerSecond) {
      this.activeRequests++;
      return;
    }
    return new Promise((resolve) => {
      this.queue.push({ resolve });
    });
  }

  release(): void {
    this.activeRequests--;
    if (this.queue.length > 0) {
      const next = this.queue.shift()!;
      this.activeRequests++;
      setTimeout(() => next.resolve(), 1000 / this.maxPerSecond);
    }
  }

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    await this.acquire();
    try {
      return await fn();
    } finally {
      this.release();
    }
  }
}

export const rateLimiter = new NotionRateLimiter();
```

**Response cache (reduce API calls in production):**

Notion data that changes infrequently (database schemas, user lists, page metadata) should be cached to stay well under the rate limit.

```typescript
// src/cache.ts — TTL cache for Notion responses
interface CacheEntry<T> {
  data: T;
  expiresAt: number;
}

export class NotionCache {
  private store = new Map<string, CacheEntry<unknown>>();
  private readonly defaultTtlMs: number;

  constructor(defaultTtlSeconds = 60) {
    this.defaultTtlMs = defaultTtlSeconds * 1000;
  }

  get<T>(key: string): T | null {
    const entry = this.store.get(key);
    if (!entry || Date.now() > entry.expiresAt) {
      this.store.delete(key);
      return null;
    }
    return entry.data as T;
  }

  set<T>(key: string, data: T, ttlSeconds?: number): void {
    const ttlMs = ttlSeconds ? ttlSeconds * 1000 : this.defaultTtlMs;
    this.store.set(key, { data, expiresAt: Date.now() + ttlMs });
  }

  invalidate(pattern: string): void {
    for (const key of this.store.keys()) {
      if (key.includes(pattern)) this.store.delete(key);
    }
  }
}

export const notionCache = new NotionCache(60); // 60-second default TTL
```

**Health check endpoint (include in every deployment):**

```typescript
// src/health.ts — verifies Notion API connectivity
import { getNotionClient } from './notion-client';
import { isNotionClientError } from '@notionhq/client';

export async function healthCheck(): Promise<{
  status: 'healthy' | 'degraded';
  notion: { connected: boolean; latencyMs: number; error?: string };
  timestamp: string;
}> {
  const timestamp = new Date().toISOString();
  const start = Date.now();

  try {
    const notion = getNotionClient();
    await notion.users.me({});
    return {
      status: 'healthy',
      notion: { connected: true, latencyMs: Date.now() - start },
      timestamp,
    };
  } catch (error) {
    const errorCode = isNotionClientError(error) ? error.code : 'unknown';
    return {
      status: 'degraded',
      notion: { connected: false, latencyMs: Date.now() - start, error: errorCode },
      timestamp,
    };
  }
}
```

### Step 2 — Deploy to Your Target Platform

Pick one platform and follow its deployment path. All three store `NOTION_TOKEN` as a secret that is injected at runtime, never committed to source.

**Option A: Vercel (serverless functions)**

Best for: Next.js apps, API routes, low-traffic webhooks. Cold starts are ~200ms for Node.js.

```bash
# Store the token as a production secret
vercel env add NOTION_TOKEN production
# Paste ntn_xxx when prompted — Vercel encrypts at rest

# Deploy
vercel --prod
```

Vercel API route using the singleton:

```typescript
// app/api/notion/query/route.ts (Next.js App Router)
import { NextResponse } from 'next/server';
import { getNotionClient } from '@/lib/notion-client';
import { rateLimiter } from '@/lib/rate-limiter';
import { notionCache } from '@/lib/cache';

export async function POST(request: Request) {
  const { databaseId, filter } = await request.json();
  const cacheKey = `db:${databaseId}:${JSON.stringify(filter)}`;

  // Check cache first
  const cached = notionCache.get(cacheKey);
  if (cached) return NextResponse.json(cached);

  try {
    const notion = getNotionClient();
    const response = await rateLimiter.execute(() =>
      notion.databases.query({ database_id: databaseId, filter, page_size: 100 })
    );

    const result = {
      pages: response.results.map((page: any) => ({
        id: page.id,
        title: page.properties?.Name?.title?.[0]?.plain_text ?? '',
        lastEdited: page.last_edited_time,
      })),
      hasMore: response.has_more,
    };

    notionCache.set(cacheKey, result, 30); // cache 30 seconds
    return NextResponse.json(result);
  } catch (error: any) {
    return NextResponse.json(
      { error: error.code ?? 'unknown', message: error.message },
      { status: error.status ?? 500 }
    );
  }
}
```

Add the health route:

```typescript
// app/api/health/route.ts
import { NextResponse } from 'next/server';
import { healthCheck } from '@/lib/health';

export async function GET() {
  const result = await healthCheck();
  return NextResponse.json(result, { status: result.status === 'healthy' ? 200 : 503 });
}
```

**Option B: Railway (container-based, always-on)**

Best for: Long-running sync services, high-frequency webhooks, apps needing persistent state.

```bash
# Set the secret via CLI
railway variables set NOTION_TOKEN=ntn_xxx

# Deploy from the current directory
railway up

# Verify
railway status
```

Railway uses `Dockerfile` or Nixpacks auto-detection. For Node.js, ensure `package.json` has a `start` script:

```json
{
  "scripts": {
    "start": "node dist/index.js",
    "build": "tsc"
  }
}
```

Railway provides persistent volumes and cron jobs, making it ideal for Notion sync services that run on a schedule.

**Option C: Fly.io (edge containers)**

Best for: Global distribution, low-latency API proxies, services needing machines in multiple regions.

```toml
# fly.toml
app = "my-notion-service"
primary_region = "iad"

[env]