From 42b832cdc42e7dc3d6b6fa8e3770b5eb008c6524 Mon Sep 17 00:00:00 2001 From: draphy Date: Tue, 3 Mar 2026 15:43:15 +0530 Subject: [PATCH] feat: [DRO-67] add comprehensive Cloudflare Workers deployment guide --- README.md | 17 ++- examples/cloudflare/README.md | 273 ++++++++++++++++++++++++++++++++++ 2 files changed, 287 insertions(+), 3 deletions(-) create mode 100644 examples/cloudflare/README.md diff --git a/README.md b/README.md index 3462d8b..907ad5c 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,8 @@ Nooxy rewrites Notion's HTML to give search engines exactly what they need: ## Quick Start +> For detailed deployment guides, see [examples](./examples). + ### 1. Install ```bash @@ -179,11 +181,20 @@ npx nooxy generate ### 5. Deploy -**Cloudflare Workers** (recommended): +Nooxy works with Cloudflare Workers (recommended) and Node.js. + +**For complete step-by-step deployment guides, see:** + +| Platform | Guide | +|----------|-------| +| **Cloudflare Workers** | [Full Deployment Guide](./examples/cloudflare/README.md) | +| **Node.js** | Coming soon | + +**Quick reference for Cloudflare Workers:** ```typescript import { initializeNooxy } from 'nooxy'; -import { SITE_CONFIG } from './nooxy/config'; +import { SITE_CONFIG } from '../nooxy/config'; const proxy = initializeNooxy(SITE_CONFIG); @@ -194,7 +205,7 @@ export default { }; ``` -**Node.js**: +**Quick reference for Node.js:** ```typescript import { initializeNooxy } from 'nooxy'; diff --git a/examples/cloudflare/README.md b/examples/cloudflare/README.md new file mode 100644 index 0000000..c9413ba --- /dev/null +++ b/examples/cloudflare/README.md @@ -0,0 +1,273 @@ +# Deploy Nooxy on Cloudflare Workers + +A complete guide to deploy your Notion site on Cloudflare Workers. + +## Prerequisites + +- [Node.js](https://nodejs.org) v18.17+ installed +- A [Cloudflare account](https://dash.cloudflare.com/sign-up) (free tier works) +- Your Notion pages set to public + +## Step 1: Create Your Project + +Open your terminal and run these commands one by one: + +```bash +# Create a new Cloudflare Workers project +npm create cloudflare@latest my-nooxy-site + +# When asked: +# - "What would you like to start with?" → Select "Hello World example" +# - "Which template?" → Select "Hello World Worker" +# - "Which language?" → Select "TypeScript" +# - "Do you want to use git?" → Your choice (Yes is fine) +# - "Do you want to deploy?" → Select "No" (we'll do this later) +``` + +Now move into your project folder: + +```bash +cd my-nooxy-site +``` + +## Step 2: Install and Initialize Nooxy + +```bash +npm install nooxy +npx nooxy init +``` + +This creates a `nooxy/` folder with configuration files at your project root. + +## Step 3: Get Your Notion Page IDs + +You need the ID of each Notion page you want to include on your site. + +1. Open your Notion page in a browser +2. Look at the URL. It looks something like: + ``` + https://www.notion.so/My-Page-Title-abc123def456789... + ``` +3. The page ID is the long string of letters and numbers at the end (32 characters) +4. Copy just the ID part: `abc123def456789...` + +**Tip:** If your URL has a custom domain or workspace name, the ID is still the last part after the final hyphen. + +## Step 4: Configure Your Site + +Open `nooxy/config.js` and update these values: + +```javascript +export const SITE_CONFIG = { + // Your website domain (use workers.dev for now if you don't have one) + domain: 'my-nooxy-site.your-subdomain.workers.dev', + + // Your Notion workspace domain + // Find this by opening any Notion page and looking at the URL + // It's usually: yourname.notion.site + notionDomain: 'yourname.notion.site', + + // Your website name (appears in browser tabs and search results) + siteName: 'My Website', + + // Map your URLs to Notion page IDs + slugToPage: { + '/': 'paste-your-home-page-id-here', + '/about': 'paste-your-about-page-id-here', + '/blog': 'paste-your-blog-page-id-here', + }, + + // ... rest of the config +}; +``` + +**Important:** Make sure your Notion pages are set to "Public" in Notion's share settings. + +## Step 5: Generate Assets + +```bash +npx nooxy generate +``` + +> Run this from your project root (where `package.json` is). Or use `npx nooxy generate --path=/your/project/path` from anywhere. + +## Step 6: Update the Worker Code + +Open `src/index.ts` and replace everything with: + +```typescript +import { initializeNooxy } from 'nooxy'; +import { SITE_CONFIG } from '../nooxy/config'; + +const proxy = initializeNooxy(SITE_CONFIG); + +export default { + async fetch(request: Request): Promise { + return proxy(request); + }, +}; +``` + +## Step 7: Test Locally + +```bash +npm run dev +``` + +Open `http://localhost:8787` in your browser. Press `Ctrl + C` to stop. + +## Step 8: Deploy + +```bash +# Log in to Cloudflare (first time only) +npx wrangler login + +# Deploy +npm run deploy +``` + +You'll get a live URL like `https://my-nooxy-site.your-subdomain.workers.dev` + +--- + +## Custom Domain (Optional) + +Skip this if you're fine with the `.workers.dev` URL. + +### If Your Domain is Already on Cloudflare + +1. Go to **Cloudflare Dashboard** → **Workers & Pages** +2. Click your worker → **Settings** → **Domains & Routes** +3. Click **Add** → **Custom Domain** +4. Enter your domain and click **Add Domain** + +Then update `domain` in `nooxy/config.js` and redeploy: + +```bash +npx nooxy generate +npm run deploy +``` + +### If Your Domain is Not on Cloudflare Yet + +You need to add your domain to Cloudflare first (you don't need to transfer it): + +1. **Cloudflare Dashboard** → **Websites** → **Add a Site** +2. Enter your domain, select **Free** plan +3. Cloudflare gives you two nameservers +4. Go to your registrar (where you bought the domain) and update the nameservers +5. Wait for propagation (usually under 1 hour) + +Then follow the steps above to connect it to your worker. + +
+Where to find nameserver settings at popular registrars + +- **GoDaddy:** My Products → Domain → DNS → Nameservers +- **Namecheap:** Domain List → Manage → Nameservers → Custom DNS +- **Google Domains:** DNS → Custom name servers +- **Porkbun:** Domain Management → Nameservers + +
+ +### Don't Have a Domain? + +Buy one from [Cloudflare Registrar](https://dash.cloudflare.com/?to=/:account/domains/register) or any registrar (Namecheap, Porkbun, etc.). Costs ~$10-15/year. + +--- + +## Adding More Pages + +To add new pages to your site: + +1. Create the page in Notion +2. Make it public (Share → Publish to web) +3. Copy the page ID from the URL +4. Add it to `slugToPage` in `nooxy/config.js`: + ```javascript + slugToPage: { + '/': 'home-page-id', + '/about': 'about-page-id', + '/blog': 'blog-page-id', + '/contact': 'your-new-page-id', // Add new pages here + }, + ``` +5. Run `npx nooxy generate` +6. Run `npm run deploy` + +--- + +## Updating Your Site + +Whenever you change your Nooxy configuration: + +```bash +npx nooxy generate +npm run deploy +``` + +Changes to your Notion content appear automatically (no redeploy needed). + +--- + +## Troubleshooting + +### "Page not found" error + +- Check that the Notion page is set to Public +- Verify the page ID is correct (32 characters, no hyphens) +- Make sure `notionDomain` matches your Notion workspace + +### "Cannot find module 'nooxy'" error + +Run `npm install nooxy` in your project folder. + +### Site looks broken or unstyled + +- Run `npx nooxy generate` after any config changes +- Clear your browser cache or try incognito mode + +### Domain not working + +- Wait up to 24 hours for DNS propagation +- Check that nameservers are correctly updated at your registrar +- Verify the domain shows "Active" in Cloudflare dashboard + +### Need more help? + +- [Open an issue on GitHub](https://github.com/draphy/nooxy/issues) +- [Join the discussions](https://github.com/draphy/nooxy/discussions) + +--- + +## Quick Reference + +| Command | What it does | +|---------|--------------| +| `npm install nooxy` | Install Nooxy in your project | +| `npx nooxy init` | Create configuration files | +| `npx nooxy generate` | Process your config changes | +| `npm run dev` | Test locally at localhost:8787 | +| `npx wrangler login` | Log in to Cloudflare | +| `npm run deploy` | Deploy to Cloudflare | + +--- + +## Project Structure + +This folder (`examples/cloudflare/`) is a working reference. Your project will have the same structure: + +``` +my-nooxy-site/ +├── src/ +│ └── index.ts # Your worker code +├── nooxy/ +│ ├── config.js # Your site configuration +│ ├── head.css # Custom CSS (optional) +│ ├── head.js # Custom JavaScript for (optional) +│ ├── body.js # Custom JavaScript for (optional) +│ └── header.html # Custom header HTML (optional) +├── package.json +└── wrangler.jsonc # Cloudflare configuration +``` +