feat(roadmap): add roadmap page with json data loading logic with sim… (#215)

…ilar UI like linear custom view
## New .env variable
- `LINEAR_API_KEY` - linear API KEY
- `LINEAR_CUSTOM_VIEW_ID` - the custom view id from linear that shows
the public roadmap
- `API_SECRET` - a secret API KEY generated by us that can be used in
endpoint to refresh roadmap data and clear cache
- `NETLIFY_API_TOKEN` - netlify api token that are used to purge CDN
cache of the /developers/roadmap page

## PR Checklist
- [ ] Linked issue added (e.g., `Fixes #123`)
- [ ] I have run `bun run format` to ensure code is properly formatted
- [ ] I have verified that `bun run lint` passes without errors
- [ ] If blog post was added:
  - [ ] Ensure images have been optimised
- [ ] Update dates to reflect the actual publishing date when merged
(file names, folder names, and frontmatter)

## Summary
<!-- What has been updated and why -->
Fixes INTORG-636

---------

Co-authored-by: JoblersTune <sarah@interledger.org>

Author: adrianboros

.env.example

@@ -0,0 +1,32 @@
+# Variables marked "required" will cause a build/runtime error if missing in production.
+# To build locally without these keys, run: bun run astro build -- --mode development
+
+# -----------------------------------------------------------------------------
+# Linear (required)
+# -----------------------------------------------------------------------------
+
+# Linear API key — used by sync functions to fetch roadmap data from Linear
+# Get from: Linear → Settings → API → Personal API keys → Create key (read-only scope is sufficient)
+LINEAR_API_KEY=lin_api_...
+
+# Linear custom view ID containing the roadmap projects (required)
+LINEAR_CUSTOM_VIEW_ID=27df73bc-50ec-4fc1-bbb2-d906236a5bbc
+
+# -----------------------------------------------------------------------------
+# Sync API (required)
+# -----------------------------------------------------------------------------
+
+# Bearer token for POST /api/sync (manual sync trigger) — set to any strong secret
+API_SECRET=
+
+# -----------------------------------------------------------------------------
+# Netlify (optional — used for CDN cache purging after sync)
+# -----------------------------------------------------------------------------
+
+# Netlify Personal Access Token
+# Get from: Netlify UI → User Settings → Applications → Personal access tokens
+NETLIFY_API_TOKEN=
+
+# Netlify Site ID — auto-injected by Netlify in production and by `netlify dev` after `netlify link`
+# Set manually only if running sync functions outside of the Netlify CLI
+# NETLIFY_SITE_ID=

.gitignore

@@ -23,8 +23,12 @@ pnpm-debug.log*
 # lock files
 bun.lock
 bun.lockb
+deno.lock
 pnpm-lock.yaml
 package-lock.json
 
 # webstorm
 .idea/
+
+# Local Netlify folder
+.netlify

.prettierignore

@@ -3,5 +3,6 @@
 node_modules
 public
 dist
+.netlify
 **/*.min.css 
 **/*.min.js

README.md

@@ -37,29 +37,48 @@ For more information about the way our documentation projects are set up, please
 
 ## Local Development
 
-We are using [Bun](https://bun.sh/) in this repository, but you could theoretically use the package manager of your choice. To install Bun, run
+This project requires the [Netlify CLI](https://docs.netlify.com/cli/get-started/) for local development. Running `bun run start` alone will produce a redirect loop — the Netlify CLI proxy is needed to handle routing correctly.
+
+### Prerequisites
+
+Install [Bun](https://bun.sh/) and the Netlify CLI:
 
 ```sh
 curl -fsSL https://bun.sh/install | bash
+npm install -g netlify-cli
 ```
 
-### 🧞 Commands
+Then link the repo to the Netlify site (one-time):
+
+```sh
+netlify login
+netlify link
+```
+
+### Running locally
+
+```sh
+bun install
+netlify dev    # http://localhost:8888
+```
 
-All commands are run from the root of the project, from a terminal:
+> **Troubleshooting:** If `netlify dev` fails with a Neon extension network error, run `netlify dev --offline` instead — this skips the extension install and everything else works normally. See [`docs/roadmap-linear-sync.md`](docs/roadmap-linear-sync.md) for details.
+
+> **Note:** The roadmap page also requires a one-time blob population step after first run. See [`docs/roadmap-linear-sync.md`](docs/roadmap-linear-sync.md) for details.
+
+### 🧞 Other commands
 
 | Command                   | Action                                           |
 | :------------------------ | :----------------------------------------------- |
 | `bun install`             | Installs dependencies                            |
-| `bun run start`           | Starts local dev server at `localhost:1103`      |
+| `netlify dev`             | Starts local dev server at `localhost:8888`      |
 | `bun run build`           | Build your production site to `./dist/`          |
 | `bun run preview`         | Preview your build locally, before deploying     |
 | `bun run astro ...`       | Run CLI commands like `astro add`, `astro check` |
 | `bun run astro -- --help` | Get help using the Astro CLI                     |
 | `bun run format`          | Format code and fix linting issues               |
 | `bun run lint`            | Check code formatting and linting                |
 
-You can substitute the `bun` commands with whatever package manager of your choice uses.
-
 ### 🔍 Code Formatting
 
 This project uses [ESLint](https://eslint.org/) for code linting and [Prettier](https://prettier.io/) for code formatting. Before submitting a pull request, please ensure your code is properly formatted:
@@ -99,6 +118,19 @@ This runs `gcloud compute url-maps invalidate-cdn-cache` against `/developers/*`
 
 For more information about the main Interledger.org infrastructure and deployment pipeline, see the [`interledger.org-v4`](https://github.com/interledger/interledger.org-v4) repository.
 
+## Netlify Serverless Functions
+
+This project uses Netlify serverless functions to power the live roadmap page:
+
+| Function                         | Purpose                                                                                              |
+| :------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| `netlify/functions/sync.mts`     | Scheduled sync — fetches roadmap data from Linear every 12 hours and caches it in Netlify Blobs      |
+| `netlify/functions/sync-now.mts` | Manual sync — exposes `POST /api/sync` (deployed) or `POST /.netlify/functions/sync-now` (local dev) |
+
+The roadmap page is server-side rendered and reads from the blob cache on each request. The CDN caches the rendered HTML for 12 hours; the sync functions purge that cache after each update.
+
+For full details on the architecture, environment variables, local development setup, and how Deploy Previews interact with the shared blob store, see [`docs/roadmap-linear-sync.md`](docs/roadmap-linear-sync.md).
+
 Thank You for Contributing! We appreciate your effort to write a blog post and share your expertise with the community!
 
 ## Writing a blog post

astro.config.mjs

@@ -4,10 +4,13 @@ import starlightLinksValidator from 'starlight-links-validator'
 import starlightFullViewMode from 'starlight-fullview-mode'
 
 import mdx from '@astrojs/mdx'
+import netlify from '@astrojs/netlify'
 import { PUBLISHED_RFC_SIDEBAR_ITEMS } from './src/data/rfcs.ts'
 
 // https://astro.build/config
 export default defineConfig({
+  output: 'static',
+  adapter: netlify(),
   site: 'https://interledger.org',
   base: '/developers',
   integrations: [