Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Landing page

web/ contains the static landing page at cjv.zxilly.com and cjv.zxilly.dev, with installer commands and platform-specific downloads. It uses React Router Framework Mode, Vite, TypeScript, Tailwind CSS, and Lingui. web/package.json declares dependency ranges and the pnpm version; web/pnpm-lock.yaml locks dependency versions.

Development and files

To start the local development server, run inside web/:

cd web
pnpm install --frozen-lockfile
pnpm dev

pnpm build generates route types, checks TypeScript, and runs the official React Router build. react-router.config.ts sets ssr: false and prerender paths derived from the Blog manifest, producing static files in web/dist/client/. pnpm preview serves that output locally. Development requires Node.js 22.22.0 or newer; production needs no React SSR server.

File or directoryContents
react-router.config.ts, src/routes.tsOfficial prerender configuration and route table
src/root.tsxHTML document, SEO metadata, and framework hydration components
src/App.tsxInstallation landing page layout, mirror toggle, and download interactions
src/hooks/use-platform.tsBrowser platform detection and download recommendations
src/generated/platforms.tsFrontend platform catalog generated from Go (internal/target/catalog.go)
src/lib/i18n.ts, src/locales/Language selection and Lingui message catalogs
src/style.css, src/components/Theme tokens and UI components
public/install.sh, public/install.ps1Public Unix and PowerShell installer scripts

To change the set of supported release platforms, update internal/target/catalog.go in Go and run go generate ./... from the repository root—never edit src/generated/platforms.ts by hand.

Platform detection

Production builds prerender React into Chinese / and English /en/ HTML through React Router Framework Mode. No React SSR server runs in production. The initial hydration uses the same generic installation methods as the build; platform detection and regional mirror defaults apply afterwards. Content, commands and documentation links remain readable without JavaScript.

src/lib/seo.ts defines localized page metadata and the homepage footer links to the matching documentation and Blog language. Both domains use canonical and hreflang URLs on .com, while .dev retains its installer commands and downloads. The mdbook-seo backend renders documentation HTML with page metadata; mdbook-sitemap generates chapter sitemaps. scripts/site_map.py reads the rendered canonical URLs and merges the plugin output with the built home and Blog pages into the site sitemap, without changing HTML.

use-platform.ts computes an initial platform match synchronously from standard browser properties (navigator.userAgent and navigator.platform), and then queries User-Agent Client Hints (navigator.userAgentData) for additional CPU architecture metadata. Detection resolves to one of three states: ready, unknown, or unsupported.

  • macOS architecture ambiguity — Many macOS browsers report an Intel (x86_64) User-Agent even on Apple Silicon (arm64) Macs. When a browser cannot reliably confirm the Mac’s CPU architecture, the install.sh script command remains available (since the shell script detects the native architecture locally), while manual downloads present both Apple Silicon and Intel options side by side.
  • Mobile and tablet browsers — Mobile operating systems and architectures without prebuilt binaries are marked unsupported, including iPadOS browsers running in desktop User-Agent mode.
  • HarmonyOS and OpenHarmony — HarmonyOS detection prioritizes the version in the OpenHarmony / HarmonyOS token and preserves its version namespace (ArkWeb, HuaweiBrowser, and Chrome versions are never treated as OS versions). Phone / Mobile tokens identify phones, and Tablet alone identifies ordinary tablets (unsupported). Tablet combined with Windows NT identifies a 2-in-1 device in tablet mode, while PC or desktop Windows NT tokens identify PCs. HarmonyOS PCs and 2-in-1 devices receive the shell installer command and native ARM64 / x86_64 download choices, whereas phones, ordinary tablets, and unclassified devices show device-specific guidance.

Compatibility tokens (Windows NT, Linux, Android) and UA Client Hints are never allowed to override HarmonyOS with Windows or Android, nor are they trusted to guess a HarmonyOS device’s native CPU architecture. Instead, the download panel explains how to run uname -m in the terminal to choose the right architecture and launch cjv-init.

Whenever you modify platform detection, run the real-browser platform tests (pnpm test:integration and pnpm test:built) and verify that an unknown architecture never produces a single wrong binary recommendation. See Testing and checks.

Translation and styling

Chinese (zh) is the Lingui source language:

  • Use <Trans> from @lingui/react/macro inside JSX.
  • Use useLingui().t for string expressions inside React components.
  • Use msg from @lingui/core/macro for message descriptors outside components.

After adding or updating UI copy in web/src/, extract the message catalogs:

pnpm i18n:extract

Then fill in the new English translations in src/locales/en/messages.po. Production page URLs determine the language. Language links update the URL, content and metadata, including browser back/forward navigation. Both development and production use the route language; saved preferences never override an explicit URL. Each render tree owns its Lingui instance so concurrent prerenders cannot mix languages. During production builds, the Lingui Vite plugin compiles the catalogs automatically.

The visual theme is defined in src/style.css, dark mode follows the operating system preference, and web fonts are bundled from local dependencies. Animations should continue to respect useReducedMotion.

The homepage retains its original wordmark, short introduction, installation panel and footer styling, adding only a Blog link beside the existing documentation, GitHub, Releases and Cangjie site links. Tutorial navigation, team-workflow explanations and article recommendations belong in the manuals or Blog rather than extending the installation page.

Publishing Blog content

The Blog lives at /blog/ and /en/blog/, with paired Chinese and English article URLs. src/content/blog/posts.json defines each slug, publication date and localized title, description and category. Matching Markdown files live under src/content/blog/zh/ and en/. Blog interface strings are kept in src/lib/blog.ts, separately from the landing page’s Lingui catalogs.

Provide both languages when adding an article. Start body headings at H2 without repeating the page H1, keep slugs stable, and link to the matching language of the .com manuals. react-router.config.ts derives all Blog prerender paths from the manifest. Markdown is parsed during the build and does not need a production API. Each article has its own canonical URL, hreflang links, description and BlogPosting data. The documentation build adds the generated Blog pages to the site sitemap.

The Blog inherits the green brand, fonts and system dark mode, using a single reading column, a table of contents and horizontally scrollable code blocks. Run pnpm test, pnpm build and pnpm test:built after changes, and inspect desktop and mobile layouts. SDK and CI commands still need validation in the documented environment; website tests do not establish that those SDK workflows ran successfully.

Deployment contents

During CI deployment, .github/workflows/pages.yml builds web/ first, and then adds platform-specific cjv-init binaries under web/dist/client/dl/ and both bilingual mdBook manuals under web/dist/client/book/. A local pnpm build in web/ does not generate those extra directories on its own. See Releases for /dl/ installer artifacts and Documentation site for the mdBook build.