Documentation

Installation

Install Chronalog in your Next.js project using pnpm:

Initialisation

Run the init command to scaffold the necessary files and directories:

This will create:

• Admin page at /app/(cms)/chronalog/page.tsx
• Settings page at /app/(cms)/chronalog/settings/page.tsx
• API routes for saving, listing, and fetching changelog entries
• GitHub OAuth authentication routes
• Configuration file at changelog.config.ts
• Changelog directory at chronalog/changelog

GitHub OAuth Setup

Chronalog uses GitHub OAuth for authentication. Set up your GitHub OAuth app:

1. Create a GitHub OAuth App at https://github.com/settings/developers
2. Set the Authorization callback URL to: http://localhost:3000/api/changelog/auth/callback
3. Add the following to your .env.local file:

Note: CHRONALOG_TOKEN_SECRET is optional for local development but recommended for production.

Requirements

• Next.js 14.0.0 or higher
• React 18.0.0 or higher
• Tailwind CSS 4.0.0 or higher
• Git (for auto-commit functionality)

Deploying to Vercel

When deploying to Vercel or other serverless platforms, Chronalog uses the GitHub API to fetch changelog entries since the filesystem is read-only. To ensure your public changelog page works correctly, you need to set up a GitHub access token.

Creating a GitHub Personal Access Token

Create a GitHub personal access token for your deployment:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a descriptive name (e.g., "Chronalog Vercel Deployment")
4. Select the appropriate scopes:
   • repo - Full control of private repositories (if your repo is private)
   • public_repo - Access public repositories (if your repo is public)
5. Click "Generate token" and copy it immediately (you won't be able to see it again)

Adding the Token to Vercel

Add the token as an environment variable in your Vercel project:

1. Go to your Vercel project dashboard
2. Navigate to Settings → Environment Variables
3. Add a new environment variable:
   • Name: CHRONALOG_GITHUB_TOKEN
   • Value: Your GitHub personal access token
   • Environment: Select all (Production, Preview, Development)
4. Click "Save"
5. Redeploy your application for the changes to take effect

How It Works

Chronalog uses the access token in the following priority order:

1. User session token - If a user is logged in via GitHub OAuth, their session token is used (highest priority)
2. Environment variable token - The CHRONALOG_GITHUB_TOKEN is used as a fallback for public pages
3. No token - For public repositories, the GitHub REST API is used without authentication (may be subject to rate limits)

Note: For private repositories, an access token is required. The environment variable token ensures your public changelog page works without requiring users to log in.

Repository Configuration (Optional)

If your Vercel deployment is not connected to Git, or if Git commands are not available in your serverless environment, you can manually specify your repository details using these environment variables:

When to use these: These are only needed if Chronalog cannot automatically detect your repository from Git commands. Vercel automatically provides VERCEL_GIT_REPO_OWNER and VERCEL_GIT_REPO_SLUG when your project is connected to Git, so you typically don't need to set these manually.

Complete Environment Variables List

Here's a complete list of all environment variables you may need in Vercel:

Required Fields

• title (string) - The title of the changelog entry
• date (string) - ISO datetime format: YYYY-MM-DDTHH:mm:ss.sssZ
• body (string) - The main content/body of the changelog entry (MDX/HTML)

Optional Fields

• version (string) - Version number (e.g., "1.0.0")
• tags (string[]) - Array of tags for categorisation
• features (string[]) - Array of feature descriptions
• bugfixes (string[]) - Array of bug fix descriptions

Example Entry

---
title: Version 1.0.0 Release
date: 2024-01-15T14:30:00.000Z
version: 1.0.0
tags:
  - "release"
  - "feature"
features:
  - "Added user authentication system"
  - "Implemented dark mode"
bugfixes:
  - "Fixed login redirect issue"
---

This release includes major new features and important bug fixes.

## Highlights

- Complete authentication overhaul
- Improved performance across the board
- Better user experience

Saving Entries

Save changelog entries via the API endpoint:

POST /api/changelog/save
Content-Type: application/json

{
  "title": "New Feature Release",
  "version": "1.0.0",
  "date": "2024-01-15",
  "tags": ["feature", "release"],
  "features": ["Added new authentication"],
  "bugfixes": ["Fixed login issue"],
  "body": "This is the main content..."
}

Reading Entries

Use the Chronalog utilities to read and list entries:

import { 
  listChangelogEntries, 
  readChangelogEntry,
  filterChangelogEntriesByTags,
  getAllTags 
} from "chronalog";

// List all entries
const entries = listChangelogEntries();

// Read a specific entry
const entry = readChangelogEntry("my-entry-slug");

// Filter by tags
const featureEntries = filterChangelogEntriesByTags(
  entries, 
  ["feature"]
);

// Get all available tags
const tags = getAllTags(entries);