Skip to main content

​
Prerequisites

Before you begin, ensure you have the required runtime environments installed:

Node.js ≥ 22

Production deployment target

Bun ≥ 1.1

Local development (recommended)
Bun is recommended for local development as it provides native TypeScript support with no compilation step. However, the deployment target is Node.js 22.
Never use Bun-specific APIs (Bun.file(), Bun.serve(), etc.) in source files — they won’t exist in the Node.js runtime at deployment.

​
Additional Requirements

  • TypeScript ≥ 5.4 (strict mode required)
  • ntn CLI for deployment (makenotion/workers-template)
  • Package manager: npm (lockfile committed) or bun

​
Installation

1

Clone the repository

Navigate to your workspace and clone the jre-notion-workers repository.
2

Install dependencies

bun install
3

Configure credentials

Set up your environment variables. See the Credentials Guide for detailed options.
4

Verify installation

Run the connection test to verify your setup:
bun run test:connection

​
Project Structure

The repository follows a clean architecture pattern: 
jre-notion-workers/
├── src/
│   ├── index.ts              # Worker registration
│   ├── shared/               # Types, clients, parsers, utils
│   │   ├── types.ts
│   │   ├── notion-client.ts
│   │   ├── agent-config.ts
│   │   ├── status-parser.ts
│   │   ├── date-utils.ts
│   │   └── block-builder.ts
│   └── workers/              # Worker implementations
│       ├── write-agent-digest.ts
│       ├── check-upstream-status.ts
│       └── create-handoff-marker.ts
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── evals/
│   └── fixtures/
├── .examples/                # Example payloads
├── package.json
├── tsconfig.json
└── README.md

​
Module System

This project uses ESM (ECMAScript Modules):
  • "type": "module" is set in package.json
  • Use .js extensions in import paths when importing from .ts files (NodeNext resolution)
import { getNotionClient } from "../shared/notion-client.js";

​
Development Commands

​
Running Locally

bun run dev
Or directly run the entry point: 
bun run src/index.ts

​
Type Checking

Run TypeScript compiler checks without emitting files: 
npm run check
This must pass before deployment. The project uses strict: true with no exceptions.

​
Build

Compile TypeScript for deployment: 
npm run build

​
Code Standards

​
Naming Conventions

TypeConventionExample
Fileskebab-casewrite-agent-digest.ts
Functions/variablescamelCasegetNotionClient
Types/interfacesPascalCaseAgentDigestInput
ConstantsSCREAMING_SNAKE_CASEDOCS_DATABASE_ID
Notion IDs32-char hex, no dashesabc123...

​
Type Safety Rules

Strict Mode

strict: true — no exceptions

No any

Use unknown then narrow

No Assertions

No non-null assertions (!) on API responses

Explicit Returns

All async functions should have explicit return types

​
Architecture Pattern

Pure logic separation:
  • Business logic (parsing, building, validating) → src/shared/ → unit tested
  • Orchestration (validate input, call logic, call Notion, return result) → src/workers/

​
Runtime Environment

  • Uses Bun runtime
  • Native TypeScript execution
  • No compilation step needed
  • Fast test execution with built-in test runner
  • Uses Node.js 22 runtime
  • Managed by Notion Workers platform
  • Deployed via ntn CLI
  • Pre-authenticated Notion client provided

​
Next Steps

Configure Credentials

Set up your environment variables and secrets

Run Tests

Learn about the testing strategy and run the test suite

Deploy Workers

Deploy your workers to production

Worker Architecture

Understand the worker system design

Build docs developers (and LLMs) love

Get started for freeTalk to us