Getting Started

Yang Chun Comment is a simple, lightweight, privacy-first commenting system. The frontend uses Lit, making it easy to embed into various frontend frameworks. The backend uses Hono and is designed to run on the Cloudflare Workers serverless platform. It is perfect for personal blogs or small websites (sometimes people just want to simply reply: Cool!).

✨ For commenters, it features:

• No registration or login required
• No real names, Emails, IP addresses, User-Agents, or Cookies are collected.
• No browser fingerprinting
• Supports Markdown syntax
• RSS Feed notifications

The following steps will guide you through the deployment so you can add Yang Chun Comment to your website.

Caution

The system design is not guaranteed to comply with any data and privacy regulations, including but not limited to GDPR (General Data Protection Regulation).

1. Preparation

Yang Chun Comment is a Monorepo project using pnpm workspaces, mainly consisting of a frontend (client) and a backend (server). The following steps use pnpm as the package manager.

Since the backend will be deployed on Cloudflare Workers, you need to sign up for a Cloudflare account. The free plan is sufficient for most personal needs.

First, clone the project from GitHub and enter the project directory:

git clone https://github.com/ziteh/yangchun-comment.git yangchun-comment

cd yangchun-comment

Install dependencies and build the project:

pnpm install

pnpm build

2. Backend (server)

Enter the backend directory from the project root:

cd server

Wrangler is the developer platform CLI tool for Cloudflare. Before performing subsequent Cloudflare operations, you need to log in to your Cloudflare account:

pnpm exec wrangler login

A. Create D1

Create a D1 database, a SQLite-compatible database service provided by Cloudflare, which Yang Chun Comment uses to store comment data. In the command below, yangchun-comment-d1 is the database name, which you can modify. If you need to specify a region, use --location or --jurisdiction (refer to Cloudflare docs). For D1 free limits, see D1 Pricing.

pnpm exec wrangler d1 create "yangchun-comment-d1" --binding "DB"

You should receive a response similar to the following. The response below shows this D1 was created in APAC (Asia Pacific). You need to copy the id from the response.

✅ Successfully created DB 'yangchun-comment-d1' in region APAC
Created your new D1 database.

To access your new D1 Database in your Worker, add the following snippet to your configuration file:
[[d1_databases]]
binding = "DB"
database_name = "yangchun-comment-d1"
database_id = "a99c5674-5526-49fd-z98e-7493ce28bsx5"

Update your wrangler.toml by pasting the id from the response above:

wrangler.toml

...

[[d1_databases]]
binding = "DB"
database_name = "yangchun-comment-d1"
database_id = "a99c5674-5526-49fd-z98e-7493ce28bsx5" # <-- Replace with your D1 ID

...

After D1 is created, initialize the database schema. Remember to replace the database name with your own if you modified it:

pnpm exec wrangler d1 migrations apply "yangchun-comment-d1" --remote

You should see a response similar to the following. Confirm and enter Y to continue:

Migrations to be applied:
┌─────────────────────────┐
│ name                    │
├─────────────────────────┤
│ 0000_initial_schema.sql │
└─────────────────────────┘
✔ About to apply 1 migration(s)
Your database may not be available to serve requests during the migration, continue? (Y/n)

B. Create KV

Create a KV Namespace, a Key-Value storage service provided by Cloudflare, which Yang Chun Comment uses to store cache data. In the command below, yangchun-comment-kv is the namespace name, which you can modify. For KV free limits, see KV Pricing.

pnpm exec wrangler kv namespace create "yangchun-comment-kv" --binding "KV"

You should receive a response similar to the following. You need to copy the id.

🌀 Creating namespace with title "yangchun-comment-kv"
✨ Success!
To access your new KV Namespace in your Worker, add the following snippet to your configuration file:
[[kv_namespaces]]
binding = "KV"
id = "506ac68ae906458692g22933d3896af3"

Update your wrangler.toml by pasting the id from the response above:

wrangler.toml

...

[[kv_namespaces]]
binding = "KV"
id = "506ac68ae906458692g22933d3896af3" # <-- Replace with your KV ID

...

C. Configure Environment Variables

Some variables in wrangler.toml need to be modified according to your needs. For full variables and descriptions, see Environment Variables:

wrangler.toml

...

[vars]
# You need to adjust these variables at minimum
ADMIN_USERNAME = "admin"                       # Admin username
PRE_POW_SALT = "MAGIC"                   # The salt for the pre-PoW
FRONTEND_URL = "http://localhost:5173" # Frontend URL
CORS_ORIGIN = "http://localhost:5173"          # CORS origin

...

Note

There is a variable check mechanism. If variable formats are incorrect, the Worker startup will fail with Environment variable validation failed. Check your environment variable settings.

Danger

Variables prefixed with SECRET_ are sensitive information. They should absolutely NOT be written in wrangler.toml, committed to version control systems (like Git), or exposed.

Refer to the following instructions to handle these secrets.

D. Configure Secrets

Yang Chun Comment requires some secrets for security. Follow the instructions below to generate and upload them. These secrets will be stored in Cloudflare Workers Secrets.

First, create an empty .dev.vars file in the server/ directory. This file is similar to .env and is used to store environment variables.

Note: Do not expose this file or commit it to version control systems (like Git).

touch .dev.vars

First is the admin login password. Yang Chun Comment uses PBKDF2-HMAC-SHA256 as the password hashing algorithm, with an output length of 32 bytes and 100,000 iterations. You can use the following Node.js script to generate it:

node generate-password-hash.js <YOUR_ADMIN_PASSWORD>

This will output a response similar to the following. Copy the last two lines to the .dev.vars file:

=== PBKDF2 Password Hash ===
Iterations: 100000
Key Length: 32 bytes
Digest: sha256

Hash:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Salt:
yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

------------------------------
Put the following secrets into your .dev.vars file:

SECRET_ADMIN_PASSWORD_HASH="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
SECRET_ADMIN_PASSWORD_SALT="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

Next, generate other secrets, including SECRET_ADMIN_JWT_KEY, SECRET_COMMENT_HMAC_KEY, SECRET_FORMAL_POW_HMAC_KEY, and SECRET_IP_PEPPER.

These secrets must be cryptographically strong random values and of sufficient length. Since the system uses SHA-256 for hashing, it is recommended that the key length be at least 32 bytes (64 Hex characters). Each secret should be unique.

You can use the provided Node.js script to automatically generate these random keys:

node generate-secret-keys.js

Add the generated keys to the .dev.vars file. When finished, the .dev.vars file should look like this:

.dev.vars

SECRET_ADMIN_PASSWORD_HASH="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
SECRET_ADMIN_PASSWORD_SALT="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

SECRET_ADMIN_JWT_KEY="zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
SECRET_COMMENT_HMAC_KEY="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
SECRET_FORMAL_POW_HMAC_KEY="bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
SECRET_IP_PEPPER="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"

Use the following command to upload these variables. --name is used to specify your Worker name:

pnpm exec wrangler secret bulk ".dev.vars" --name "yangchun-comment-server"

You should see a response similar to the following. Since we haven’t created the Worker yet, it asks if we want to create a new Worker and add secrets to it. Enter Y to continue:

🌀 Creating the secrets for the Worker "yangchun-comment-server"
✔ There doesn't seem to be a Worker called "yangchun-comment-server".
  Do you want to create a new Worker with that name and add secrets to it? (Y/n)

…

🌀 Creating new Worker "yangchun-comment-server"...
✨ Successfully created secret for key: SECRET_ADMIN_PASSWORD_HASH
✨ Successfully created secret for key: SECRET_ADMIN_PASSWORD_SALT
✨ Successfully created secret for key: SECRET_ADMIN_JWT_KEY
✨ Successfully created secret for key: SECRET_COMMENT_HMAC_KEY
✨ Successfully created secret for key: SECRET_FORMAL_POW_HMAC_KEY
✨ Successfully created secret for key: SECRET_IP_PEPPER

Finished processing secrets file:
✨ 6 secrets successfully uploaded

Note

There is a secret check mechanism. If the secret length is insufficient or the format is incorrect, the Worker startup will fail with Environment variable validation failed. Ensure secrets meet requirements.

Danger

Variables prefixed with SECRET_ are sensitive information. Keep them safe and do not disclose them. Once you complete this section, you do not need to (and should not) view or store these secrets again. They are stored in Cloudflare Workers Secrets and cannot be read or exported.

E. Deploy Worker

Use the following command to deploy the Worker to Cloudflare. --name is used to specify your Worker name:

pnpm exec wrangler deploy --name "yangchun-comment-server"

You should see a response similar to the following, which includes your Worker endpoint URL:

Total Upload: 1130.82 KiB / gzip: 203.68 KiB
Worker Startup Time: 39 ms
Your Worker has access to the following bindings:

...

Uploaded yangchun-comment-server (5.42 sec)
Deployed yangchun-comment-server triggers (1.83 sec)
  https://yangchun-comment-server.<YOUR_SUBDOMAIN>.workers.dev
Current Version ID: 1b58de00-53b1-4320-b897-0a035b035c42

You can try opening this URL https://yangchun-comment-server.<YOUR_SUBDOMAIN>.workers.dev/rss/site/<RSS_SITE_PATH> in your browser to check if the Worker is deployed successfully. This is the site-wide RSS Feed URL. Remember to replace <YOUR_SUBDOMAIN> and <RSS_SITE_PATH> with your actual values. Note there is no trailing slash. If successful, you should see an XML response similar to:

<rss version="2.0">
  <channel>
    <title>All Site Comments</title>
    <link>https://your-frontend-url.com</link>
    <description>Latest 0 comments from all posts on the site</description>
    <lastBuildDate>Mon, 12 Jan 2026 11:04:52 GMT</lastBuildDate>
  </channel>
</rss>

That’s it for the backend! You can open the Dashboard to check its status.

3. Frontend (client)

Since the frontend is published as a Web Component generated by Lit, you can embed it into almost any frontend framework (e.g., React, Vue, Svelte, etc.) or even vanilla JavaScript.

A. Install Package

Open your frontend project and install the Yang Chun Comment frontend package @ziteh/yangchun-comment-client. Since this project is not yet stable, it is recommended to pin the version:

pnpm add @ziteh/yangchun-comment-client@0.2.0-alpha.1

Then import and use it in your project. Basic usage is as follows. Note that some attribute values need to be replaced:

• post: Unique identifier for the post or page the comment belongs to. You can use the post slug or ID.
• apiUrl: The URL of your deployed backend Worker.
• lang: Language setting, adjust as needed.
• adminName: Admin name, displayed as the post author.
• prePowDifficulty and prePowSalt: These values must match the backend settings.

<yangchun-comment
  post="default-post"
  apiUrl="https://yangchun-comment-server.<YOUR_SUBDOMAIN>.workers.dev"
  lang="en-US"
  adminName="ZiTe"
  prePowDifficulty="2"
  prePowSalt="MAGIC"
></yangchun-comment>

Here is a Vanilla JavaScript example:

// Vanilla example

import "./style.css";
import "@ziteh/yangchun-comment-client";

document.querySelector<HTMLDivElement>("#app")!.innerHTML = `
  <div>
    <yangchun-comment
      post="default-post"
      apiUrl="https://yangchun-comment-server.<YOUR_SUBDOMAIN>.workers.dev"
      lang="en-US"
      adminName="ZiTe"
      prePowDifficulty="2"
      prePowSalt="MAGIC"
    ></yangchun-comment>
  </div>
`;

B. Adjust CSS

You can adjust the appearance of Yang Chun Comment via CSS variables to match your site design. Here is an example:

yangchun-comment {
  --ycc-primary-color: #2563eb;
  --ycc-primary-hover: #1d4ed8;
  --ycc-text-color: #ffffff;
  --ycc-text-secondary: #a3a3a3;
  --ycc-bg-color: #242424;
  --ycc-bg-secondary: #4d4d4d;
  --ycc-border-color: #757578;
  --ycc-error-color: #ef4444;
}