DEV Community: David Raphi

How to Host a Personal Website for Free in 10 Minutes (Notion + Cloudflare)

David Raphi — Wed, 28 Oct 2026 03:22:31 +0000

Most personal website tutorials start with a framework. This one starts with a page you have already written, and it shows you how to host a personal website for free without adding another CMS.

If your CV, project notes, publication list, or lab journal already lives in Notion, you do not need another CMS. You need a way to put that page on your own domain, make it indexable, and then stop thinking about it.

That is the narrow problem Nooxy solves. It is an open-source Notion reverse proxy that runs on Cloudflare Workers. You point it at your published Notion pages, and it serves them on your domain with clean URLs, canonical tags, a sitemap, and your own CSS and JavaScript.

Using Notion as a CMS keeps the writing workflow you already have. The free personal website hosting comes from Cloudflare Workers. Adding a Notion custom domain is optional. You can see the result on draphy.org, os.draphy.org, and em-ucd.com. One Nooxy user also built a fan-made Expedition 33 music wiki that documents 196 songs across four albums. It is available in English and Spanish.

This guide goes from an empty terminal to a live site. The deploy itself takes about 10 minutes. Hosting and TLS cost $0 on Cloudflare's free plan. The only optional cost is the domain name, usually $10 to $15 per year. You can start on a free *.workers.dev URL if you do not have one yet.

I am the maintainer of Nooxy, so this comparison is not neutral. I have tried to make it fair and specific, with the trade-offs marked clearly so you can decide if it fits. Nooxy is not affiliated with Notion or Cloudflare.

Last checked: October 2026. Nooxy v2.0.0.

The short version

What you get: A personal website on your domain, with content managed in Notion.

Stack: Notion for content, Nooxy for the proxy and SEO, Cloudflare Workers for hosting.

Time: About 10 to 15 minutes if your domain is already on Cloudflare. First-time DNS can take longer.

Cost: $0 for hosting, TLS, and Notion's free plan. A custom domain is roughly $10 to $15 per year. A *.workers.dev URL is free.

Coding: None for the setup. You copy commands and edit one config file.

Best for: PhD students, researchers, writers, consultants, and developers who already write in Notion and want a low-maintenance site.

Not a fit for: E-commerce, logged-in memberships, or a completely terminal-free setup. The comparison below shows the closest alternatives.

Jump to: The 10-minute setup · SEO checklist · Troubleshooting · The main trade-offs · FAQ

Why I built this

I wanted a personal site at draphy.org. I already documented everything in Notion, so paying another $20 a month for a CMS felt backwards.

I tried Fruition first. It was the free option most people recommended at the time, but its maintenance had slowed and I wanted something I could adjust myself. I tried a few smaller proxies too, but they were harder to verify.

So I wrote the small piece I actually needed: a proxy that sits between Notion and the browser, fixes the SEO plumbing, and lets me inject my own styles and scripts. No database. No build pipeline for content. No runtime dependencies. No monthly bill.

I have run Nooxy on my own sites since 2025. It is a focused open-source tool, maintained by me, with a test suite and a habit of fixing what breaks when Notion changes. That is the honest version.

What you actually need

Requirement	Why you need it	Cost
Node.js 22 or newer	Runs the Nooxy CLI and Wrangler	Free
A Cloudflare account	Hosts the Worker and manages DNS	Free, no credit card for Workers Free
At least one published Notion page	Your content	Free plan is enough for a solo site
A domain name (optional)	A professional URL	Roughly $10 to $15 per year
10 to 15 minutes	Setup	Your time

Check your Node version first:

node -v

If it prints v22 or higher, you are ready. If not, install the current LTS from nodejs.org. Nooxy requires Node 22, so an old global Node install is the most common reason the CLI fails.

You do not need to know Git, React, or how Cloudflare Workers work. You do need to be comfortable pasting commands into a terminal. That is the one real barrier, and I will not pretend otherwise.

How Notion, Nooxy, and Cloudflare fit together

The architecture is intentionally boring.

Visitor -> yourdomain.com
              |
              v
     Cloudflare Worker (Nooxy)
              |  fetch the published page
              v
     your-workspace.notion.site
              |
              v
     HTML with your domain, SEO tags, CSS, and JS

Notion is the CMS. You write and edit there. Published changes show up on the site without a rebuild.

Nooxy is the translation layer. It maps a clean path like /about to a Notion page ID, fetches the public page, and rewrites the response. It removes Notion's noindex tag when indexing is enabled, adds a canonical URL, injects Open Graph and Twitter tags, adds a WebPage JSON-LD block with a nested WebSite, and serves /sitemap.xml and /robots.txt.

Cloudflare Workers is the host. The Worker runs on Cloudflare's edge network. The free plan includes 100,000 requests per day, which is far more than a personal site usually needs. You can check the current limits in Cloudflare's docs.

Cloudflare also has a cache that can sit in front of the Worker. It is off by default. Turn it on and a cached page is returned without running the Worker or fetching Notion. The setup below keeps it off; the Optional extras section shows the change if you want it.

There is no Notion API key, no integration token, and no database sync. Nooxy serves the published page itself. That also means it keeps working with Notion database views, filters, and live updates, because it is not converting your page to static HTML.

The trade-off is equally simple: this is a live proxy, not a static site generator. By default, every request fetches from Notion and rewrites the HTML, so the live page shares Notion's availability. That is what keeps edits live and databases interactive. If you need a site that always stays up independently of Notion, a static generator is the better fit.

What "free" actually means

A custom domain is not free, and I do not want anyone to start this guide thinking otherwise.

Here is the real cost picture for this stack, checked in October 2026:

What	What it costs	Notes
Cloudflare Workers	$0	100,000 requests per day on the free plan
TLS certificate	$0	Created and renewed by Cloudflare
Notion	$0	The free plan is enough for a solo personal site
Nooxy	$0	MIT licensed
Custom domain	Roughly $10 to $15 per year	Optional. The `*.workers.dev` URL is free

That is the whole cost picture for this tutorial. The comparison near the end covers Notion Sites, Super.so, Fruition, and a custom static site, including what each one charges. Prices change, so check the current pages before you buy.

If $10 a year is still too much, launch on the free *.workers.dev URL first. You can add the domain later without rebuilding anything.

Cloudflare's Workers Cache has no separate price. A cache hit skips the Worker's CPU time, but it still counts as a request against the daily limit. The Optional extras section has the setup.

The 10-minute setup

You will do 11 steps. Steps 1 through 8 get you a live site on a workers.dev URL. Step 9 adds your domain. Steps 10 and 11 add pages and styling. The 10 minutes is hands-on time, not reading time, so read the steps once before you start.

If you get stuck, the full Cloudflare deployment guide has the same steps with more detail and troubleshooting. The Nooxy documentation links in this article are pinned to the commit this tutorial was written against, so they will not break when the README changes.

Step 1: Create the Cloudflare project

In an empty folder you want to work in, run:

npm create cloudflare@latest my-nooxy-site

You will be asked a few questions. Choose these options:

Question	What to select
What would you like to start with?	Hello World example
Which template?	Hello World Worker
Which language?	TypeScript
Do you want to use git?	Your choice. Yes is fine
Do you want to deploy?	No, we will do it later

The exact wording may change as Cloudflare updates its CLI. The important part is a plain Worker with TypeScript. Do not choose a static site or Pages template. Nooxy needs a Worker because it proxies requests.

Move into the project:

cd my-nooxy-site

At this point you should have src/index.ts, package.json, and wrangler.jsonc.

Step 2: Install Nooxy and create the config

Run these inside my-nooxy-site:

npm install nooxy
npx nooxy init

npx nooxy init creates a nooxy/ folder:

my-nooxy-site/
├── src/
│   └── index.ts
├── nooxy/
│   ├── config.js
│   ├── head.css
│   ├── head.js
│   ├── body.js
│   └── header.html
├── package.json
└── wrangler.jsonc

The four optional files are where your custom CSS, JavaScript, and header HTML go. You can leave them empty for now.

Step 3: Publish your Notion pages and copy the IDs

Every Notion page has a 32-character page ID. Nooxy uses that ID to connect a URL path to a page.

For each page you want on your site:

Open the page in Notion.
Click Share in the top right.
Open the Publish tab.
Turn on Publish to web or click Publish.
Copy the public link.

The published link looks like this:

https://your-workspace.notion.site/Your-Page-Title-abc123def456789012345678901234ab

The page ID is the 32 hex characters at the end of the URL path, after the last hyphen:

abc123def456789012345678901234ab

Ignore anything after a ?, such as ?pvs=4. That is a tracking parameter, not part of the ID.

The hostname, your-workspace.notion.site, is your notionDomain. You will need both the ID and the hostname in the next step.

A few details that save time:

The page ID contains only letters a through f and numbers 0 through 9.
If your link shows a UUID with hyphens, remove the hyphens. Nooxy expects 32 characters with no separators.
The page must be published as a Notion Site. The general "Anyone on the web with link" setting is not the same thing.
The page ID is an identifier, not a password. It does not grant edit access, but it does point at a public page.

Check your subpages before you publish. Notion publishes a page's subpages by default. If you have private notes, drafts, or anything you would not put on the public internet under that page, restrict the subpage permissions first. Notion's own help page also notes that published page metadata can include contributor names, profile photos, and email addresses. Review the page before you make it public.

Notion explains the publishing flow in Publish a Notion Site.

Step 4: Configure the site

Open nooxy/config.js. Do not replace the whole file. Edit the matching values in place, and leave the imports and the generated custom* fields at the bottom alone.

The four required values look like this:

export const SITE_CONFIG = {
  // Your site's hostname, without https://
  // You can start with your workers.dev URL and update it after the first deploy.
  domain: 'my-nooxy-site.YOUR-SUBDOMAIN.workers.dev',

  // The hostname of your published Notion site
  notionDomain: 'your-workspace.notion.site',

  // Your name or site name
  siteName: 'Your Name',

  // URL path -> 32-character Notion page ID
  slugToPage: {
    '/': 'YOUR_HOME_PAGE_ID',
    '/about': 'YOUR_ABOUT_PAGE_ID',
    '/projects': 'YOUR_PROJECTS_PAGE_ID',
  },

  // Leave the rest of the file as it is.
};

Your actual file also has seo, pageMetadata, fof, subDomains, and other options. They are commented out by default. You can uncomment the ones you need later. The configuration reference lists every field.

For a basic site, add this seo block inside SITE_CONFIG:

seo: {
  indexing: true,
  defaultAuthor: 'Your Name',
  brandReplacement: 'Your Name',
},

indexing: true is the default, but setting it explicitly makes the intent clear. It tells Nooxy to remove Notion's noindex tag and add canonical and robots tags. brandReplacement replaces "Notion" in meta tags with your name or brand.

If you do not know your workers.dev subdomain yet, leave the placeholder. Deploy once in Step 8, copy the real URL, update domain, and redeploy. The site works either way. Only the canonical URLs are wrong until you fix it.

One common mistake: domain is a hostname, not a full URL. Use example.com, not https://example.com.

Step 5: Generate the injected assets

Run:

npx nooxy generate

This reads head.css, head.js, body.js, and header.html, minifies them, and writes the generated strings that config.js imports. It creates nooxy/generated/.

Run this command every time you change anything in the nooxy/ folder. That is the rule that prevents the "why is my CSS not showing up?" problem later.

Step 6: Connect Nooxy to the Worker

Open src/index.ts and replace everything in it with this:

import { initializeNooxy } from 'nooxy';
import { SITE_CONFIG } from '../nooxy/config';

const proxy = initializeNooxy(SITE_CONFIG);

export default {
  async fetch(request: Request): Promise<Response> {
    return proxy(request);
  },
};

Save the file. That is the entire integration. initializeNooxy returns a function that takes a standard Request and returns a standard Response.

Step 7: Test locally

Start the local Worker:

npm run dev

Open http://localhost:8787. You should see your Notion page, served by Nooxy.

Press Ctrl + C when you are done.

If it does not work, check these first:

Problem	What to check
Page not found	Is the page published? Is the page ID exactly 32 characters? Does `notionDomain` match the published hostname?
Blank page	The page ID is usually wrong. Copy it again from the published URL
Cannot find module 'nooxy'	Run `npm install nooxy` in the project root
Port already in use	Stop the other process, or let Wrangler pick another port

Nooxy automatically uses localhost for canonical URLs during local development, so you do not need to change domain just to test.

Step 8: Deploy

npx wrangler login

This opens a browser window. Click Allow.

Then deploy:

npm run deploy

When it finishes, Wrangler prints a URL like this:

https://my-nooxy-site.your-subdomain.workers.dev

Open it. Your Notion page is now live on the internet.

If that URL does not match the domain in nooxy/config.js, update domain, then run:

npx nooxy generate
npm run deploy

You now have a working site. The rest is making it yours.

Step 9: Put it on your own domain

This is the part that makes the site feel real. It is also the only part that can cost money.

If you do not have a domain yet, buy one from Cloudflare Registrar, Namecheap, or Porkbun. A .com is usually in the $10 to $15 per year range. Prices vary by extension. Do not buy hosting. You do not need it.

If your domain is already on Cloudflare

Go to Cloudflare Dashboard and open Workers & Pages.
Select your Worker.
Go to Settings > Domains & Routes.
Click Add > Custom Domain.
Enter your domain, for example example.com, and confirm.

Cloudflare creates the DNS record and the TLS certificate for you. You do not need to add a CNAME manually. In fact, a Custom Domain cannot be created if the hostname already has a CNAME record, so delete any old record for that hostname first.

If your domain is not on Cloudflare yet

In the Cloudflare dashboard, go to Websites > Add a Site.
Enter your domain and choose the Free plan.
Cloudflare gives you two nameservers.
At your registrar, replace the current nameservers with Cloudflare's.
Wait until the domain shows Active. This is usually under an hour, but it can take up to 24 hours.
Then follow the Custom Domain steps above.

Update the config

Once the domain is attached, change domain:

domain: 'example.com',

Then run:

npx nooxy generate
npm run deploy

Make `www` work

example.com and www.example.com are different hostnames. Adding only one will not make the other work.

For SEO, pick one canonical version and redirect the other. The usual choice is www to apex:

Add www.example.com as a second Custom Domain on the same Worker.
Add this to nooxy/config.js:

subDomains: {
  www: {
    redirect: 'https://example.com',
  },
},

Run npx nooxy generate and npm run deploy.

Now https://www.example.com returns a 301 redirect to https://example.com. All traffic and link equity point at one hostname.

If you prefer the opposite direction, reverse the values. Do not serve the same content on both hostnames without a redirect. That is duplicate content, and it splits whatever search authority you earn.

The Cloudflare custom domain docs confirm the important detail: Custom Domains require an exact hostname match, and Cloudflare creates the DNS record and certificate for you.

Step 10: Add more pages

To add a page:

Create it in Notion.
Publish it.
Copy the 32-character page ID.
Add a path and ID to slugToPage:

slugToPage: {
  '/': 'YOUR_HOME_PAGE_ID',
  '/about': 'YOUR_ABOUT_PAGE_ID',
  '/projects': 'YOUR_PROJECTS_PAGE_ID',
  '/contact': 'YOUR_CONTACT_PAGE_ID',
  '/docs/getting-started': 'YOUR_DOCS_PAGE_ID',
},

Run:

npx nooxy generate
npm run deploy

Nested paths work. The sitemap is generated from this map, so any page you want search engines to discover should be in slugToPage.

Step 11: Make it yours

Nooxy gives you four injection points. They are all optional.

File	What it does	When it runs
`nooxy/head.css`	Custom CSS	Injected into `<head>`
`nooxy/head.js`	Early JavaScript	Before page content loads
`nooxy/body.js`	Main JavaScript	Before `</body>`
`nooxy/header.html`	Custom header HTML	At the top of the page body

A small CSS starting point:

/* nooxy/head.css */
.notion-topbar {
  display: none !important;
}

.notion-page-content {
  max-width: 900px;
  margin: 0 auto;
}

A simple header:

<!-- nooxy/header.html -->
<nav class="site-nav">
  <a href="/">Home</a>
  <a href="/about">About</a>
  <a href="/projects">Projects</a>
  <a href="/contact">Contact</a>
</nav>

After any change in nooxy/, run:

npx nooxy generate
npm run deploy

One detail from the docs: Nooxy injects its own stylesheet after yours, so a rule with the same specificity can lose even if it appears first. If you need to override Nooxy's own styles, use a more specific selector as well as !important. The project files documentation has examples.

Optional extras you may want later

You do not need any of these to launch. The table covers the four settings people ask about most often. All but the last live in nooxy/config.js:

Setting	What it does
`fof: { page: 'YOUR_404_PAGE_ID', slug: '/404' }`	Sends unknown paths to a published Notion page instead of a plain 404
`googleFont: 'Inter'`	Loads a Google Font site-wide
`nooxy: { showBadge: false }`	Hides the small "Made with Nooxy" badge, which is shown by default
`configKey`	Lets one Worker serve several sites, each with its own config

One SEO caveat on fof: it redirects unknown paths with a 301, so the custom page returns a 200 rather than a true 404. That is friendlier for visitors, but if accurate status codes matter to you, leave fof off.

The configKey option is the only one that changes src/index.ts. Instead of passing the config directly, pass an object with a stable key:

const siteA = initializeNooxy({ configKey: 'site-a', config: SITE_A });
const siteB = initializeNooxy({ configKey: 'site-b', config: SITE_B });

Then choose the site by hostname in your fetch handler. The README section on hosting several sites has the complete example. If you omit configKey, Nooxy falls back to the site's domain, but an explicit key is clearer and is required when two sites share a domain.

As always, run npx nooxy generate and npm run deploy after changing the config.

Turn on Workers Cache

Every uncached request runs the Worker and fetches the Notion page. That is what keeps edits instant, but it is also the slowest part of a page load. Cloudflare's Workers Cache stores the finished HTML at the edge and returns it without running the Worker at all. It is the right cache for a Worker. A normal Cache Rule will not do this, because the rule sits with the zone cache, not in front of the Worker.

Two changes. First, turn it on in wrangler.jsonc:

"cache": {
  "enabled": true
},

This needs Wrangler 4.69 or newer. The project you created in Step 1 already has a current Wrangler version.

Second, give the HTML an edge TTL. Notion sends cache-control: public, max-age=0, must-revalidate, and Nooxy passes that through. At max-age=0, Cloudflare will not serve a cached copy. Wrap the response in src/index.ts and set an edge-only header:

import { initializeNooxy } from 'nooxy';
import { SITE_CONFIG } from '../nooxy/config';

const proxy = initializeNooxy(SITE_CONFIG);

export default {
  async fetch(request: Request): Promise<Response> {
    const response = await proxy(request);
    const headers = new Headers(response.headers);
    const type = headers.get('content-type') || '';

    if (response.status === 200 && type.includes('text/html')) {
      headers.set('cloudflare-cdn-cache-control', 'public, max-age=300');
    }

    return new Response(response.body, {
      status: response.status,
      statusText: response.statusText,
      headers,
    });
  },
};

cloudflare-cdn-cache-control is read by Cloudflare and stripped before the response reaches the browser. The browser still revalidates on each visit, so visitors do not keep a stale page. The edge keeps the HTML for five minutes. Use 60 seconds if you edit often, or 3600 if you rarely change the page.

The status check matters. Without it, a 503 during a Notion outage would also be cached for five minutes, which turns a short outage into a longer one.

Deploy, then check it:

curl -I https://example.com/
curl -I https://example.com/

The second response should include cf-cache-status: HIT. The first is a miss while the cache fills.

Two caveats. Edits can take up to the TTL to appear. A redeploy starts a fresh cache because the Worker version is part of the cache key, so deploy when you need a change out immediately. And do not turn this on if you use configKey to serve several domains from one Worker: the cache key is the path, not the hostname, so two sites would share entries for the same path.

If you would rather keep every request live, leave the cache off. The site works fine without it.

The SEO checklist after launch

Nooxy handles the technical plumbing. The writing, links, and rankings are still yours to earn. Here is what to do after the site is live.

1. Check the three URLs

Open these in a browser:

https://example.com/robots.txt
https://example.com/sitemap.xml
https://example.com/

robots.txt should point to your sitemap. sitemap.xml should list every slug in slugToPage. The homepage should load.

2. Inspect the page source

Use View Page Source (Ctrl+U on Windows/Linux, Cmd+U on Mac), not the rendered DOM in DevTools. Nooxy rewrites the HTML on the server, so the source is what crawlers see.

Search for:

<link rel="canonical" and confirm it points to your domain, not notion.site.
<meta name="robots" content="index, follow and confirm it is present.
<title> and <meta name="description">.
<script type="application/ld+json"> and confirm the WebPage schema and its nested WebSite.

If the canonical URL points to notion.site, your domain value is wrong. Fix it and redeploy.

3. Add per-page metadata

This is the highest-impact SEO change you can make. Notion's default titles and descriptions are generic, and they often include the word "Notion".

Add a pageMetadata block to nooxy/config.js:

pageMetadata: {
  'YOUR_HOME_PAGE_ID': {
    title: 'Ada Lovelace | Mathematician and Writer',
    description: 'Notes, papers, and projects by Ada Lovelace.',
    image: 'https://example.com/og/home.jpg',
    author: 'Ada Lovelace',
  },
  'YOUR_ABOUT_PAGE_ID': {
    title: 'About Ada Lovelace',
    description: 'A short biography, current work, and contact details.',
    author: 'Ada Lovelace',
  },
},

Use the page ID as the key. The image should be an absolute URL, ideally 1200 by 630 pixels. Add your own social image at that URL.

Then run npx nooxy generate and npm run deploy.

Nooxy also exposes seo.keywords and seo.aiAttribution. They are optional and do not replace a clear title, description, and page copy.

4. Submit the sitemap to search engines

For Google:

Open Google Search Console.
Add a property. A Domain property is easiest if your DNS is on Cloudflare.
Verify ownership. Cloudflare makes the DNS verification a copy-paste job.
Go to Sitemaps and submit https://example.com/sitemap.xml.
Use URL Inspection on your homepage and click Request indexing.

For Bing, add the site in Bing Webmaster Tools and submit the same sitemap. You can also import from Google Search Console.

Do not expect instant results. Notion's own documentation says Notion Sites can take up to four weeks to be indexed. A custom domain with a submitted sitemap can be faster, but no one can promise a timeline.

5. Add analytics only if you will use it

Nooxy supports a GA4 measurement ID:

googleTagID: 'G-XXXXXXXXXX',

That is optional. If you install analytics, use it to learn which pages people actually read. Do not install three tools and then ignore all of them.

Updating your site later

There are two loops, and mixing them up causes most of the confusion.

What you changed	What to run
Content in Notion	Nothing. Publish the page and the site updates, within the cache TTL if you turned on Workers Cache
`nooxy/config.js`, `head.css`, `head.js`, `body.js`, or `header.html`	`npx nooxy generate` then `npm run deploy`
Domain or DNS settings	Update them in Cloudflare and the `domain` field, then redeploy
A new page	Add it to `slugToPage`, then `npx nooxy generate` and `npm run deploy`

Content changes are live because Nooxy fetches the published Notion page on each request. Config and asset changes need a redeploy because they are compiled into the Worker.

With Workers Cache on, the edge can serve a copy for up to the TTL you set. Redeploying starts a fresh cache, because the Worker version is part of the cache key.

That is the maintenance model: almost none for content, a package update every few months, and a redeploy when you change the design or a route.

Troubleshooting

Symptom	Likely cause	Fix
404 or "Page not found"	Page is not published, the ID is wrong, or `notionDomain` is wrong	Publish the page, copy the 32-character ID again, and use the `.notion.site` hostname
Blank page	Usually a wrong page ID	Re-copy the ID from the published URL
CSS is not applied	You forgot to regenerate or redeploy	Run `npx nooxy generate` and `npm run deploy`
SEO tags are missing	`seo.indexing` is false, you are looking at the rendered DOM, or the Worker was not redeployed	Set `indexing: true`, view the page source, and redeploy
Edited a Notion page but the site shows the old copy	Workers Cache is serving the cached HTML	Wait for the TTL, or redeploy to start a fresh cache. A zone "Purge Everything" does not clear the Worker cache
`Cannot find module 'nooxy'`	Nooxy is not installed in the project root	Run `npm install nooxy` inside `my-nooxy-site`
Custom domain does not work	DNS is not active, an old record conflicts, or the domain is not attached to the Worker	Wait for Active, remove the conflicting record, and add the Custom Domain
`www` does not work	`www` is not attached, or there is no redirect	Add `www` as a Custom Domain and configure `subDomains`
Local server will not start	Wrong folder or port conflict	`cd` into the project and stop the other process

The pinned troubleshooting section and the Cloudflare guide's troubleshooting section cover more cases.

The main trade-offs

Nooxy is built for public, content-first sites. It does a few things well instead of trying to be every CMS. Here is the short list.

The setup is terminal-first, but it is short. You paste the commands in this guide and edit one config file. After that, everyday updates happen in Notion. The payoff is full control over CSS, JavaScript, and SEO instead of a locked builder.
Content is served live from Notion. That makes edits appear immediately and keeps database views interactive. Without caching, the site follows Notion's uptime: if Notion is unreachable, Nooxy returns a 503, not a stale copy. Workers Cache changes that trade: a cached page can survive a short outage, but edits can lag by the TTL. If you need a site that always stays up independently, a static export is still the better fit.
It publishes public pages, not accounts. Nooxy does not bundle login, memberships, payments, or private content. Comments can be added with a third-party script. If your site needs accounts or a full application, pair Nooxy with another service or choose an app stack.
The domain is the only likely bill. Hosting, TLS, and the Workers free tier are $0. A custom domain is roughly $10 to $15 per year, and a *.workers.dev URL is free.

Nooxy is open source, MIT licensed, and supported through GitHub issues, with tests and CI in the repo. If those points fit your site, the rest of this guide is the fast path.

Nooxy vs Notion Sites, Super.so, and Fruition

Option	What it costs	Best for	What to know
Nooxy + Cloudflare Workers	$0 hosting. Domain roughly $10 to $15 per year, or $0 on `*.workers.dev`	A free, live Notion site with full CSS, JS, and SEO control	Short terminal setup. Optional edge cache
Notion Sites	Free basic publishing. A Plus plan with the custom domain add-on is roughly $18 to $22 per month	The fastest official, click-based option	Custom domain and advanced SEO are paid
Super.so	Free on `super.site`. Custom domain plans start at $16 per month	A polished static Notion site	Paid for a custom domain. Static export loses live database filtering
Fruition	Free	Existing legacy setups	Maintenance has slowed; check recent activity before starting
Custom static site	Hosting can be $0. Your time is the cost	Full control and a custom build	You own the build and maintenance

A fair summary:

Nooxy is a free, open-source option that keeps Notion live and gives you full design and SEO control. The trade-off is a short terminal setup. Content follows Notion uptime unless you turn on the optional edge cache.
Notion Sites is the easiest official option. It is click-based and quick to launch; custom domains and advanced SEO are paid.
Super.so is a polished static builder with a paid custom-domain plan. It is a good choice if you want a static export and do not need live database filtering.
Fruition helped popularize this approach, but its maintenance has slowed. Check the recent activity before choosing it for a new site.
A custom static site gives you maximum control if you enjoy owning the build pipeline.

Nooxy's sweet spot is free hosting, live Notion content, and full control, with a short setup.

Who Nooxy is for

Nooxy is a strong fit if:

You already write in Notion and want one source of truth.
You want a custom domain without a monthly hosting bill.
You want full control over your CSS, JavaScript, and SEO tags.
You want live Notion databases and filtering on your site.
You are a PhD student, researcher, writer, consultant, or developer who needs a clean Notion portfolio website, lab site, or blog.
You are comfortable copying a few terminal commands once.

Choose another tool if:

You need a completely click-based setup and never want to open a terminal. Notion Sites is the closest fit.
You need accounts, payments, private content, or a full web application. Nooxy is a publishing layer, not an app framework.
You need a fully static site that stays online independently of Notion. A static export is the better fit.

If the second list sounds like your project, Notion Sites or Super.so are good choices for that job. Nooxy is the better fit when you want live Notion content, full control, and no monthly hosting bill.

FAQ

Is Nooxy really free?

Yes for hosting. Nooxy is MIT licensed, Cloudflare Workers has a free tier with 100,000 requests per day, and Notion's free plan is enough for a solo personal site. A custom domain is the only likely cost, usually $10 to $15 per year. The *.workers.dev URL costs nothing.

Do I need a Notion custom domain?

No. You can launch on the free *.workers.dev URL and add a domain later. A Notion custom domain looks more professional and helps with branding, but it is not required to get the site working.

Do I need to know how to code?

No for the setup. The guide gives you every command and one config file to edit. Customizing CSS or JavaScript is optional, and that is where code helps. The launch itself does not require writing code.

Can I use Notion databases on my website?

Yes. Nooxy serves the published Notion page, so database views and filtering that work on the public Notion page should work on your domain. It does not use the Notion API, and it does not convert the page to static HTML.

Do content changes appear automatically?

Yes. Edit and publish the page in Notion, and the site reflects the change on the next request. If you turned on Workers Cache, the change appears within the cache TTL. Changes to files in nooxy/ are different: run npx nooxy generate and npm run deploy.

Should I turn on Cloudflare caching?

Yes if you want faster loads and can wait a few minutes for an edit to appear. No if you serve several domains from one Worker with configKey, because the cache key does not include the hostname. The Optional extras section has a five-minute setup that leaves browser caching alone.

Is a Nooxy site good for SEO?

A Nooxy site serves your published Notion website on your own domain and gives you the technical pieces: no noindex, canonical URLs, clean paths, per-page titles and descriptions, Open Graph and Twitter tags, a sitemap, robots.txt, and a WebPage JSON-LD block with a nested WebSite. Rankings still depend on your content, your competition, and your links. No tool can guarantee a position.

How is this different from Notion Sites and Super.so?

Notion Sites is the official, click-based option. Custom domains and advanced SEO are paid. Super.so is a polished static site builder for Notion, also paid for a custom domain. Nooxy is free and open source, keeps live Notion content, and gives you full CSS, JS, and SEO control. The launch is terminal-based, and the guide walks through every command.

What happens if Notion goes down?

Without caching, Nooxy fetches the published page on each request, so your site follows Notion's uptime. That is the trade-off for live edits and interactive databases. If Notion is unreachable, Nooxy returns a 503 rather than a stale copy. With Workers Cache on, a recently cached page can survive a short outage, but edits can take up to the TTL to appear. If you need a fully static fallback, a static export is the better fit.

Can I use Cloudflare Pages instead of Workers?

Not with this guide. Cloudflare Pages is built for static assets. Nooxy needs a Worker because it proxies requests and rewrites the HTML response. The guide uses Workers for that reason.

How do I move away later?

Your content stays in Notion, and your domain stays yours. Export your Notion pages, point the domain at the new host, and update the domain field if you keep Nooxy around. There is no proprietary database to migrate.

The 10-minute checklist

[ ] Node.js 22 or newer installed
[ ] Cloudflare account created
[ ] Notion page published, with subpage permissions checked
[ ] npm create cloudflare@latest my-nooxy-site
[ ] npm install nooxy and npx nooxy init
[ ] Page IDs and notionDomain copied
[ ] nooxy/config.js edited
[ ] npx nooxy generate run
[ ] src/index.ts replaced
[ ] npm run dev tested at localhost:8787
[ ] npx wrangler login and npm run deploy completed
[ ] Custom domain and www redirect configured
[ ] pageMetadata added
[ ] Sitemap submitted to Google Search Console

Final thoughts

Most people do not need a custom CMS. They need a place to write and a boring pipe to the web.

If you already write in Notion, Nooxy is that pipe. It is not the right tool for every site, but for a public, content-first personal site it is a strong fit. If you want a site you can set up in about 10 minutes, host for $0, and update from Notion without touching a build pipeline, this is the fast path.

If you try it:

Star the repo if it saves you money or time.
Open an issue if something breaks. Include the error and the page ID format, never private content.
Share your site in Discussions. I genuinely like seeing what people build.
Read the pinned Cloudflare guide if you want the longer version of this tutorial.

What are you putting online: a portfolio, a lab notebook, or a blog? Tell me in the comments. I read them.

About the author: David Raphi is a full-stack engineer and the maintainer of Nooxy. He has shipped systems for US government agencies and leads election-critical platforms. He writes about Notion, Cloudflare, and zero-dependency tooling.

GitHub · X · LinkedIn · contact@draphy.org

Sources and further reading

Nooxy README and Cloudflare deployment guide (pinned to the version used here)
Notion pricing
Notion: Publish a Notion Site
Notion Sites availability and pricing
Super.so pricing
Fruition repository
Cloudflare Workers limits
Cloudflare Workers Cache
Cloudflare Workers custom domains

Why Thousands of Developers Are Mass Migrating to PushForge for Web Push Notifications

David Raphi — Fri, 19 Jun 2026 13:37:26 +0000

"crypto.createECDH is not a function" - If you've seen this error, you're not alone. Here's why the web push landscape is finally changing.

If you've ever tried implementing push notifications on Cloudflare Workers, Vercel Edge, or any modern edge runtime, you've probably hit the same wall that thousands of developers face every month:

TypeError: crypto.createECDH is not a function

Or maybe this one:

ReferenceError: https.request is not available in edge runtime

These errors aren't bugs in your code. They're symptoms of a fundamental problem: the most popular web push library was built for a world that no longer exists.

The Uncomfortable Truth About web-push

For years, web-push has been the de facto standard for sending push notifications in Node.js. With 18+ million monthly downloads, it's the default choice that tutorials recommend, Stack Overflow answers reference, and ChatGPT suggests.

But here's what those recommendations don't tell you:

The Promise	The Reality
"Works everywhere"	Fails on Cloudflare Workers (#718)
"Simple setup"	Requires 5+ nested dependencies
"Production ready"	Node.js deprecation warnings in v24
"Modern JavaScript"	Uses legacy `crypto.createECDH` API

The issue has been open since 2022. The workarounds are fragile. The compatibility flags are band-aids. And the edge computing revolution isn't waiting.

Enter PushForge: Built for Where You're Deploying Today

PushForge is a zero-dependency web push library built entirely on the Web Crypto API, the same standard that runs in every modern browser, every edge runtime, and every JavaScript environment.

import { buildPushHTTPRequest } from "@pushforge/builder";

const { endpoint, headers, body } = await buildPushHTTPRequest({
  privateJWK: VAPID_PRIVATE_KEY,
  subscription: userSubscription,
  message: {
    payload: { title: "Hello!", body: "This works everywhere." },
    adminContact: "mailto:admin@example.com"
  }
});

await fetch(endpoint, { method: "POST", headers, body });

That's it. No polyfills. No compatibility flags. No "it works on my machine."

The Comparison Developers Are Making

Feature	PushForge	web-push
Dependencies	0	5+ (with transitive deps)
Cloudflare Workers	Yes	No (#718)
Vercel Edge Functions	Yes	No
Convex	Yes*	No
Deno	Yes	Limited
Bun	Yes	Partial
TypeScript	Native	@types package
Bundle Size	~15KB	~150KB+ with deps

* Convex requires "use node"; directive

The Numbers: Organic Growth That Speaks Volumes

100,000+ monthly downloads and growing. Zero paid marketing. Just developers solving real problems and telling others.

PushForge launched in April 2025 and has seen consistent month-over-month growth as edge computing adoption accelerates. The trajectory tells you which direction the industry is moving.

Why PushForge Works Where web-push Fails

The difference comes down to one architectural decision: standards vs. legacy APIs.

web-push approach (Node.js specific):

const crypto = require('crypto');
const https = require('https');
const ecdh = crypto.createECDH('prime256v1'); // Node.js only

PushForge approach (Web Standards):

const keyPair = await crypto.subtle.generateKey(
  { name: 'ECDH', namedCurve: 'P-256' },
  true, ['deriveBits']
); // Works everywhere

The Web Crypto API is:

Available in every modern browser
Supported by Cloudflare Workers, Vercel Edge, Deno, Bun
Part of Node.js 20+ without flags
The W3C standard for cryptographic operations

PushForge doesn't "polyfill" or "shim" its way to compatibility. It's built on the foundation that every JavaScript runtime shares.

Try Before You Trust: The Interactive Playground

Don't take our word for it. Test PushForge in your browser right now:

pushforge.draphy.org

The playground lets you:

Quick Test: Enable notifications, send a test message, see it arrive
Topic Channels: Subscribe to named topics, target specific groups
Full Customization: Icons, images, action buttons, vibration patterns
Push Options: Test urgency levels (battery hints), TTL, topic replacement
Cross-Browser: Chrome, Firefox, Safari 16+, Edge, Brave

The backend? A single Cloudflare Worker using buildPushHTTPRequest(). Zero dependencies. The same code you'd write.

Subscriptions auto-expire (5 minutes for quick test, 1 hour for topics). No accounts. No data stored. Just push notifications, working.

Getting Started in 60 Seconds

1. Install

npm install @pushforge/builder

2. Generate VAPID Keys

npx @pushforge/builder vapid

Save the output: public key for your frontend, private key (JWK) for your server.

3. Subscribe Users (Frontend)

const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: VAPID_PUBLIC_KEY
});
// Send subscription to your server

4. Send Notifications (Server)

import { buildPushHTTPRequest } from "@pushforge/builder";

const { endpoint, headers, body } = await buildPushHTTPRequest({
  privateJWK: JSON.parse(process.env.VAPID_PRIVATE_KEY),
  subscription,
  message: {
    payload: {
      title: "New Message",
      body: "You have a notification!",
      icon: "/icon.png",
      data: { url: "/messages" }
    },
    adminContact: "mailto:you@example.com",
    options: {
      ttl: 3600,
      urgency: "high"
    }
  }
});

const response = await fetch(endpoint, { method: "POST", headers, body });

Platform Examples Ready to Copy

Cloudflare Workers:

export default {
  async fetch(request, env) {
    const { endpoint, headers, body } = await buildPushHTTPRequest({
      privateJWK: JSON.parse(env.VAPID_PRIVATE_KEY),
      subscription: await request.json(),
      message: {
        payload: { title: "Hello from the Edge!" },
        adminContact: "mailto:admin@example.com"
      }
    });
    return fetch(endpoint, { method: "POST", headers, body });
  }
};

Vercel Edge Functions:

export const config = { runtime: "edge" };

export default async function handler(request: Request) {
  const { endpoint, headers, body } = await buildPushHTTPRequest({
    privateJWK: JSON.parse(process.env.VAPID_PRIVATE_KEY!),
    subscription: await request.json(),
    message: {
      payload: { title: "Edge Notification" },
      adminContact: "mailto:admin@example.com"
    }
  });
  await fetch(endpoint, { method: "POST", headers, body });
  return new Response("Sent");
}

Deno:

import { buildPushHTTPRequest } from "npm:@pushforge/builder";

const { endpoint, headers, body } = await buildPushHTTPRequest({
  privateJWK: JSON.parse(Deno.env.get("VAPID_PRIVATE_KEY")!),
  subscription,
  message: {
    payload: { title: "Hello from Deno!" },
    adminContact: "mailto:admin@example.com"
  }
});

await fetch(endpoint, { method: "POST", headers, body });

What Makes PushForge Different

TypeScript-First, Not TypeScript-Added

PushForge isn't a JavaScript library with type definitions bolted on. It's written in TypeScript from the ground up:

import type { 
  BuilderOptions,
  PushMessage,
  PushSubscription
} from "@pushforge/builder";

Your IDE knows the shape of every parameter. Your compiler catches mistakes before runtime. Your code documents itself.

Security Built In, Not Bolted On

PushForge validates everything before processing:

VAPID key structure (EC P-256 curve with required x, y, d parameters)
Subscription endpoints (must be valid HTTPS URLs)
p256dh keys (65-byte uncompressed P-256 point format)
Auth secrets (exactly 16 bytes)
Payload size (max 4KB per Web Push spec)
TTL bounds (max 24 hours per VAPID spec)

Invalid input fails fast with clear error messages, not cryptic failures deep in the crypto stack.

The Roadmap: What's Coming

PushForge is actively developed. Here's what's on the horizon:

Batching & Queuing: Bulk notification delivery with rate limiting
Built-in Retry Logic: Automatic error handling for push service failures
Framework Examples: Ready-to-use templates for React, Vue, Next.js, SvelteKit
Service Worker Templates: Drop-in notification handling code

Follow development: github.com/draphy/pushforge

The Developer Community

PushForge welcomes contributions. The workflow is straightforward:

Open an issue describing your change
Fork the repository
Create a branch: username/wpn-issuenumber-description
Follow conventional commit guidelines
Submit a pull request

The codebase uses modern tooling:

Biome for fast formatting and linting
Vitest for comprehensive testing
Semantic Release for automated versioning
GitHub Actions for CI/CD

Why Developers Are Switching

Here's what the migration typically looks like:

Before (web-push):

const webpush = require('web-push');

webpush.setVapidDetails(
  'mailto:admin@example.com',
  publicKey,
  privateKey
);

// Hope you're not on Cloudflare Workers...
await webpush.sendNotification(subscription, payload);

After (PushForge):

import { buildPushHTTPRequest } from "@pushforge/builder";

const { endpoint, headers, body } = await buildPushHTTPRequest({
  privateJWK,
  subscription,
  message: { payload, adminContact: "mailto:admin@example.com" }
});

// Works on ANY runtime with fetch()
await fetch(endpoint, { method: "POST", headers, body });

The API is intentionally minimal. You get endpoint, headers, and body. You use fetch(). That's the entire interface, and it works everywhere fetch() works.

The Bottom Line

The web has evolved. Serverless is the default. Edge computing is mainstream. The tools should match the territory.

PushForge is:

Zero dependencies (no supply chain surprises)
Web standards based (no Node.js lock-in)
TypeScript native (no type guessing)
Edge ready (Cloudflare, Vercel, Deno, Bun - all first-class)
Battle tested (100,000+ monthly downloads and growing)
Open source (MIT licensed, transparent development)

web-push served its era well. But if you're deploying to modern infrastructure, you deserve a modern foundation.

Get Started Now

npm install @pushforge/builder

Documentation: github.com/draphy/pushforge
npm: npmjs.com/package/@pushforge/builder
Playground: pushforge.draphy.org

PushForge is MIT licensed and open source. Created by David Raphi.

Have questions? Open an issue. Found a bug? PRs welcome. Building something cool? I'd love to hear about it.

🚀 Just shipped Nooxy - turn your Notion workspace into a personal website in 5 mins for free

David Raphi — Fri, 02 Jan 2026 09:06:56 +0000

How an open-source Notion reverse proxy saved me from reinventing the wheel

GitHub: github.com/draphy/nooxy · npm: npmjs.com/package/nooxy

The Moment I Almost Over-Engineered Everything

It started with a simple goal: I wanted a personal website at draphy.org. Somewhere to put my projects, write about stuff I'm learning, maybe host my resume. Nothing fancy.

My first instinct? Build a production-level CMS from scratch.

I'm a developer. I know React, Next.js, databases, all that stuff. I could totally build something custom. I was already sketching database schemas in my head. User auth, CMS backend, maybe even a headless setup with Sanity or something.

Then reality hit me.

Why am I building enterprise architecture for a site that'll get maybe 50 visitors a month? This isn't a startup. Nobody's asking for features. I don't need to scale to a million users. It's literally just me putting stuff on the internet.

I was about to spend weeks building something I could set up in minutes.

The Notion Problem (And Why Existing Solutions Didn't Work)

I already document everything in Notion anyway. Notes, project ideas, random thoughts at 2am. It's all there. And Notion has this "Publish to Web" thing that lets you share pages publicly.

Perfect, I thought. I'll just publish my Notion pages and point my custom domain to them.

Then I saw the pricing.

The Real Cost of Notion's Custom Domain

Turns out Notion buries the real cost:

Plus Plan: $10/month (annual) or $12/month (monthly)
Custom Domain Add-on: Additional $8/month (annual) or $10/month (monthly)
Total: $18-22/month just to use your own domain

For a personal website that I update maybe once a week, that's $216-264/year.

And for that money? You still can't add custom CSS. Can't inject JavaScript. Can't control your SEO meta tags properly. You're stuck with whatever Notion decides looks good.

The Search for Alternatives

So I went looking for alternatives. Someone must have solved this already, right?

Fruition was everywhere in search results. Cloudflare Workers script, reverse proxy for Notion, open-source, free. Looked perfect.

It wasn't.

I checked the GitHub repo. 189 open issues. Blank screens, broken navigation, databases not rendering after some Notion update in 2023. The project's basically dead.

People were frustrated:

"Site is not loading... a white screen with an infinitely looping loading circle."

"Back button functionality is broken, causing the signup screen to appear when using browser back navigation."

"Database not rendered - after Notion update 09.2023"

The project is effectively abandoned, with dozens of people scrambling to piece together workarounds that take hours to implement. And even then, there's no guarantee they'll work.

NoteHost was another option. At least it's an actual npm package, which was nice. But last update was like 10 months ago, barely any community around it, and it was missing stuff I wanted.

I tried a few other GitHub repos too. notion-custom-domain, notion-proxy, things like that. Same story everywhere: outdated, barely documented, half-working.

The "Why Not Build It Myself?" Moment

After wasting an entire Saturday on broken Fruition configs and reading through GitHub issues that went nowhere, I just stopped.

Wait. I'm a developer. I know how reverse proxies work. Why am I fighting someone else's broken code when I could just... write my own?

So that's what I did. I called it Nooxy because all the good names were taken and I was tired.

What is Nooxy?

Nooxy is a Notion reverse proxy. TypeScript, zero dependencies, works on Cloudflare Workers or Node.js. You point it at your Notion pages, it serves them on your domain.

What's actually different about it:

Zero Dependencies

I went a bit obsessive here, but no regrets. Zero runtime dependencies means:

Faster cold starts on edge computing platforms
Smaller bundle size
No security vulnerabilities from third-party packages
No dependency conflicts or version mismatches

When you deploy to Cloudflare Workers, it's just your code. No bloat.

Works Where You Need It

Runs on:

Cloudflare Workers (what I use)
Node.js 18.17+
Anything with Request/Response support really

The 5-Minute Setup

If you already have a Notion page published, you can have your custom domain working in under 5 minutes:

# 1. Install nooxy
npm install nooxy

# 2. Initialize configuration
npx nooxy init

# 3. Edit your config (add your domain and Notion page IDs)
# 4. Generate required files
npx nooxy generate

# 5. Deploy to Cloudflare Workers

That's literally it. I spent more time picking the domain name than setting this up.

The Stuff That Actually Matters

Clean URLs with Slug Mapping

Instead of ugly Notion URLs like notion.so/My-Page-abc123def456..., you get:

slugToPage: {
  '/': 'YOUR_HOME_PAGE_ID',
  '/about': 'YOUR_ABOUT_PAGE_ID',
  '/projects': 'YOUR_PROJECTS_PAGE_ID',
  '/blog': 'YOUR_BLOG_PAGE_ID',
}

Your visitors see yourdomain.com/about, not a 32-character hash.

Full Customization Control

Inject custom CSS, JavaScript, and HTML:

/* nooxy/head.css */
.notion-topbar {
  display: none !important; /* Hide Notion's default navigation */
}

.notion-page-content {
  max-width: 1200px;
  margin: 0 auto;
}

Add custom functionality:

// nooxy/body.js
document.addEventListener('DOMContentLoaded', function() {
  // Add smooth scrolling, analytics, custom interactions... whatever you need
  console.log('Your Notion site, your rules.');
});

SEO That Doesn't Suck

Notion's SEO is pretty bad out of the box. With Nooxy you can actually control:

Meta tags per page: Titles, descriptions, the works
Open Graph stuff: So your links don't look terrible when shared
Twitter Cards: Same deal for Twitter/X
JSON-LD: For the SEO nerds (I am one)

pageMetadata: {
  'YOUR_PAGE_ID': {
    title: "'My Custom Title - Draphy',"
    description: "'A description optimized for search engines',"
    image: 'https://yourdomain.com/og-image.jpg',
    author: 'David Raphi',
  },
}

Local Development Support

Test your site locally before deployment:

// Nooxy automatically detects localhost and adjusts
// No special configuration needed
const proxy = initializeNooxy(SITE_CONFIG);

Run wrangler dev and see your changes instantly at localhost:8787.

Multi-Instance Support

Running multiple Notion sites? Nooxy supports that:

const prodProxy = initializeNooxy({
  configKey: 'production',
  config: productionConfig,
});

const stagingProxy = initializeNooxy({
  configKey: 'staging',
  config: stagingConfig,
});

Each instance gets its own cache and configuration.

Automatic Minification

The CLI automatically minifies your custom CSS, JavaScript, and HTML during the build process:

npx nooxy generate  # Minifies by default
npx nooxy generate --no-minify  # Skip minification if needed

How It Stacks Up (Honestly)

Look, I built this thing so I'm biased. But here's the actual comparison:

Feature	Nooxy	Fruition	NoteHost	Notion Sites
Price	Free	Free	Free	$18-22/month
Custom Domain	Yes	Yes	Yes	Yes
Custom CSS/JS	Yes	Limited	Yes	No
SEO Control	Full	Partial	Partial	Limited
TypeScript	Yes	No	Yes	N/A
Zero Dependencies	Yes	No	No	N/A
Actively Maintained	Yes	No (189 issues)	Partially	Yes
CLI Tools	Yes	No	Yes	N/A
Local Dev Support	Yes	No	Partial	N/A
Multi-instance	Yes	No	No	N/A

Use Nooxy If...

You'll probably like it if you:

Don't want to pay monthly for something this simple
Want to actually customize your site (CSS, JS, whatever)
Care about SEO
Like testing locally before deploying
Are fine with Cloudflare Workers or Node.js

Skip Nooxy If...

Not gonna pretend it's for everyone:

You hate terminals (you'll need to run a few commands)
You want official Notion support (this is just me)
You're not using Cloudflare or Node
You need fancy analytics dashboards built-in
You need visitors to see real-time edits or collaboration stuff

What About Just Paying Notion?

Fair question. Notion Sites isn't terrible if you:

Have the budget ($18-22/month adds up though)
Don't care about custom styling
Just want it to work with zero effort

Nothing wrong with that. I just didn't want another monthly subscription for something I could build in a weekend.

How It's Going For Me

Been running os.draphy.org on Nooxy for a while now.

Setup: Took like 5 minutes. Most of that was finding my Notion page IDs.

Speed: It's on Cloudflare's edge network so it's fast everywhere. Haven't had complaints.

Maintenance: Basically none. I forget it's even running most of the time.

Customization: I've got my own nav, custom styles, proper SEO. Stuff that Notion just won't let you do.

Getting Started

Want to try it? Here's the quick version:

1. Install and Initialize

npm install nooxy
npx nooxy init

This creates a nooxy/ directory with all configuration files.

2. Configure Your Site

Edit nooxy/config.js:

export const SITE_CONFIG = {
  domain: 'yourdomain.com',
  notionDomain: 'your-workspace.notion.site',
  siteName: 'Your Site Name',

  slugToPage: {
    '/': 'YOUR_HOME_PAGE_ID',
    '/about': 'YOUR_ABOUT_PAGE_ID',
  },

  // These are auto-generated, just import them
  customHeadCSS: HEAD_CSS_STRING,
  customHeadJS: HEAD_JS_STRING,
  customBodyJS: BODY_JS_STRING,
  customHeader: HEADER_HTML_STRING,
};

3. Find Your Notion Page IDs

Open your Notion page → Share → Copy link. The ID is the 32-character string at the end:

notion.so/My-Page-Title-abc123def456789012345678901234
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                        This is your page ID

4. Generate and Deploy

npx nooxy generate  # Creates minified string files

# Then deploy to Cloudflare Workers
wrangler deploy

5. Point Your Domain

In Cloudflare, add a CNAME record pointing to your Worker.

Done.

Why I Built It This Way

A few things I kept in mind:

Don't overbuild. A personal site doesn't need a CMS.

Dependencies are debt. Every package you add is a future breaking change waiting to happen. I wanted something I wouldn't have to fix every time some library updated.

Make it actually usable. CLI tools, TypeScript, local dev. Not because they're trendy but because I actually wanted to use this thing.

Found a Bug? Want to Contribute?

It's open source (MIT). PRs welcome.

Code: github.com/draphy/nooxy
Issues: github.com/draphy/nooxy/issues
Discussions: github.com/draphy/nooxy/discussions

Wrapping Up

I wanted a personal website. I almost spent weeks building a CMS I didn't need. Then I almost paid Notion $20/month for features I could build myself.

Instead I spent a weekend building Nooxy. Now my site runs for free, looks how I want, and I don't think about it.

If you use Notion and want a custom domain without the subscription, maybe give it a try. Five minutes, free, you own everything.

If it's useful, star it on GitHub. If it's broken, open an issue. Either way, thanks for reading.

About the author: David Raphi is a full-stack engineer who's shipped systems for US government agencies (Florida DCF, Republican Party of Florida) and led teams delivering election-critical platforms in 1-week sprints. Lives in Cloudflare's stack and has a thing for zero-dependency packages (PushForge is another one).

GitHub · Twitter/X · LinkedIn · contact@draphy.org · david@draphy.org

🚀PushForge: Modern Web Push Notifications Made Simple🚀

David Raphi — Tue, 22 Apr 2025 21:44:30 +0000

I'm thrilled to introduce PushForge v1.0.0, my latest open-source contribution to the web development ecosystem. PushForge is a zero-dependency toolkit designed to make Web Push Notifications implementation seamless across multiple platforms including Node.js, Browsers, Deno, Bun, and even Cloudflare Workers.

🔗 GitHub: github.com/draphy/pushforge
📦 npm: npmjs.com/org/pushforge
🛠️ builder: npmjs.com/package/@pushforge/builder

Why I Built PushForge ❓

When my team needed push notifications for a project, we discovered existing libraries were unnecessarily heavy and restrictive, especially for edge computing environments. This constraint led us to develop a custom solution, which eventually inspired me to create a more comprehensive package with broader compatibility.

PushForge addresses these challenges by providing:

A lightweight solution with zero external dependencies
Cross-platform compatibility for modern JavaScript environments
TypeScript-first development for robust applications
Complete control over the notification process

🔑 Key Features

Cross-Platform Compatibility

PushForge works seamlessly across multiple environments:

Node.js (v16+)
Web Browsers
Deno
Bun
Cloudflare Workers

This versatility ensures that regardless of your tech stack, you can implement push notifications without platform-specific workarounds.

Zero Dependencies

PushForge is engineered to be lightweight and self-contained, making it especially valuable for edge computing environments where bundle size is critical. By eliminating external dependencies, we reduce potential security vulnerabilities and ensure a smaller footprint in your projects.

TypeScript-First Design

The entire library is built with TypeScript, providing comprehensive type definitions out of the box. This approach delivers:

Improved developer experience with autocomplete suggestions
Type safety to catch errors during development
Better documentation through type annotations

Complete VAPID Authentication & Web Push Protocol Support

PushForge implements the full Web Push Protocol specification, ensuring your notifications are secure and compatible with all modern browsers.

⚙️ Technical Deep Dive

Web Push Protocol Implementation

PushForge implements several critical components of the Web Push Protocol:

VAPID Authentication (JWT with ES256)

PushForge uses the ES256 algorithm (ECDSA using P-256 curve and SHA-256 hash) to create and verify JSON Web Tokens (JWTs) for Voluntary Application Server Identification (VAPID). This process:

Generates a JWT using the server's private key
Signs it with the ES256 algorithm
Includes the server's contact information
Sets appropriate expiration times (up to 24 hours)

The resulting authorization header allows push services to validate that your server is authorized to send notifications to the user.

ECDH Key Exchange

Elliptic Curve Diffie-Hellman (ECDH) key exchange enables secure communication between your server and the user's browser:

The browser generates a public/private key pair during subscription
Your server receives the public key (p256dh)
PushForge uses ECDH to create a shared secret using your server's generated key pair and the user's public key
This shared secret becomes the basis for encryption

HKDF Key Derivation

HMAC-based Key Derivation Function (HKDF) transforms the shared ECDH secret into appropriate encryption keys:

Combines the shared secret with the authentication secret (auth) provided by the browser
Uses a salt value (randomly generated for each message)
Derives encryption key and nonce (initialization vector) for AES-GCM

AES-GCM Encryption

Advanced Encryption Standard with Galois/Counter Mode (AES-GCM):

Encrypts the notification payload using the derived encryption key
Provides authenticated encryption (data integrity and confidentiality)
Incorporates appropriate padding to obscure message length
Outputs the encrypted content ready for transmission

Compliant Implementation Details

PushForge follows RFC 8291 (Message Encryption for Web Push) standards, ensuring:

Content-Encoding: aes128gcm format
Proper salt generation and record size limits
Correct padding implementation
Authentication tag handling

⚒️ Development Workflow

PushForge employs modern development tools to ensure code quality and streamlined contributions:

Semantic Release

Automated versioning and changelog generation based on conventional commit messages, which:

Determines version numbers automatically (major, minor, patch)
Generates detailed release notes
Publishes updates to npm when merging to main branch

GitHub Actions for CI/CD

Continuous integration and deployment pipelines that:

Run the test suite on every pull request
Verify code formatting and linting
Ensure type checking passes
Automate the release process

Biome for Code Quality

Biome provides fast, modern formatting and linting:

Enforces consistent code style
Catches potential bugs early
Runs as part of pre-commit checks

Testing with Vitest

Comprehensive test coverage using Vitest:

Unit tests for core functionality
Integration tests for different environments
Fast execution through Vite's architecture

Project Management with Linear

Linear helps track issues and plan development:

Manages the feature roadmap
Coordinates sprint planning
Keeps issue backlog organized
Integrates with GitHub for streamlined workflow

💡 When to Use PushForge

PushForge is particularly well-suited for projects that require:

Edge Computing Compatibility: Deploy to serverless or edge environments without worry about dependencies or platform limitations.
TypeScript Projects: Benefit from full type safety and improved developer experience.
Custom Push Logic: Implement complex notification strategies with full control over the process.
Cross-Platform Solutions: Build unified notification systems that work across different JavaScript environments.

📈 Future Plans

I'm actively working on expanding PushForge with these planned features:

Batching & Queuing System

Efficient bulk notification delivery
Rate limiting and automatic retry mechanisms
Priority-based queuing

Built-in Request Functionality

Currently, you provide your own fetch implementation
Future versions will include built-in request handling
Support for automatic error handling and retries

Legacy GCM Support

Backward compatibility for older notification systems
Support for Google Cloud Messaging legacy endpoints

Comprehensive Examples

Ready-to-use examples for popular frameworks (React, Vue, Angular, etc.)
Server-side implementations for Node.js, Express, Fastify, etc.
Service worker templates for quick implementation

Getting Started with PushForge

Here's a quick guide to implementing PushForge in your project:

Step 1: Installation

Choose your preferred package manager:

# NPM
npm install @pushforge/builder

# Yarn
yarn add @pushforge/builder

# pnpm
pnpm add @pushforge/builder

Step 2: Generate VAPID Keys

Use the built-in CLI tool to generate your VAPID keys:

npx @pushforge/builder generate-vapid-keys

This will output a public key and private key that you'll use for authentication.

Step 3: Send Notifications from Your Server

import { buildPushHTTPRequest } from "@pushforge/builder";

// Load the private key from your secure environment
const privateJWK = process.env.VAPID_PRIVATE_KEY;

// User subscription from browser push API
const subscription = {
  endpoint: "https://fcm.googleapis.com/fcm/send/DEVICE_TOKEN",
  keys: {
    p256dh: "USER_PUBLIC_KEY",
    auth: "USER_AUTH_SECRET",
  },
};

// Create message with payload
const message = {
  payload: {
    title: "New Message",
    body: "You have a new message!",
    icon: "/images/icon.png",
  },
  options: {
    ttl: 3600, // Time-to-live in seconds
    urgency: "normal", // Options: "very-low", "low", "normal", "high"
    topic: "updates", // Optional topic for replacing notifications
  },
  adminContact: "mailto:admin@example.com", // Contact information
};

// Build the push notification request
const { endpoint, headers, body } = await buildPushHTTPRequest({
  privateJWK,
  message,
  subscription,
});

// Send the push notification
const response = await fetch(endpoint, {
  method: "POST",
  headers,
  body,
});

🫂 Join the Community

Contributions to PushForge are welcome and encouraged! The project follows a structured workflow for contributions as outlined in the Contributing Guidelines.

Whether you want to:

Report bugs or suggest features
Improve tests or documentation
Submit pull requests

Here's how to contribute:

Create an issue in the GitHub tracker describing your proposed change
Wait for a Linear issue number to be assigned
Fork the repository and create a branch with the proper naming convention:

   username/wpn-issuenumber-issuetitle

Make your changes following our commit guidelines
Submit a pull request linking to the issue

Let's build the best push notification solution together! 💪

📖 References

My work on PushForge was informed by these key resources:

I'm excited to see what you'll build with PushForge! Feel free to star the repository, open issues, or reach out with questions. Together, we can make web push notifications simpler and more accessible for developers everywhere.