notion-deploy-integration

name	notion-deploy-integration
description	Deploy Node.js applications that use the Notion API to production on Vercel, Railway, or Fly.io. Use when deploying Notion-powered backends, setting up NOTION_TOKEN in production secrets, configuring serverless singleton patterns, or adding health checks that verify Notion connectivity. Trigger with "deploy notion app", "notion production", "notion vercel deploy", "notion railway", "notion fly.io".
allowed-tools	Read, Write, Edit, Bash(npx:*), Bash(vercel:*), Bash(railway:*), Bash(fly:*)
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion","deployment","serverless"]
compatibility	Designed for Claude Code

Deploy Notion-Integrated Applications

Overview

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.

Deep code lives in references/ so this file stays a lean walkthrough. Read a reference when a step needs the full module, then Write or Edit the code into your project's src/.

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

Authentication

Every request authenticates with an internal integration token (NOTION_TOKEN, prefix ntn_), created at notion.so/my-integrations and passed as auth to the client. In production the token is stored as an encrypted platform secret and injected at runtime — never committed to source. Store it with vercel env add NOTION_TOKEN production, railway variables set NOTION_TOKEN=..., or fly secrets set NOTION_TOKEN=.... Each database or page must also be explicitly shared with the integration in the Notion UI, or queries return ObjectNotFound.

Instructions

Step 1 — Prepare the application for production

Build a production entry point with four modules: a Notion client singleton, a rate limiter, a response cache, and a health check. The singleton is the essential piece — serverless containers recycle unpredictably, so a module-level client reuses connections across warm invocations instead of paying cold-start and rate-limit cost per request:

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

let :  |  = ;

  ():  {
   (!client) {
     (!process..) {
        ();
    }
    client =  ({
      : process..,
      : process.. ===  ? . : .,
      : ,
    });
  }
   client;
}