From a6f5f0b649dfea91682d41c2b3be33c97f6b5d3f Mon Sep 17 00:00:00 2001 From: Maofeng Date: Sun, 20 Sep 2026 16:49:28 +0800 Subject: [PATCH] docs: rewrite project readme --- README.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 127 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 87bd5bc..1bb6dba 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,139 @@ # Simple React App Kit -Simple React App Kit is a reusable React application kit built with TanStack -Start, shadcn/ui, and workspace packages. +Simple React App Kit is a production-oriented React workspace for building application interfaces without assembling the foundation from scratch. It includes a runnable TanStack Start application, shared shadcn/ui components, feature packages, internationalization, documentation, and tested integration patterns. -## Adding components +[Open the documentation](https://react-app-kit.go-slim.dev) ยท [English documentation](https://react-app-kit.go-slim.dev/en-US/) -To add components to your app, run the following command at the root of your `web` app: +## What you get -```bash -pnpm dlx shadcn@latest add button -c apps/web +- A TanStack Start application with routing, SSR, responsive layout, and light/dark themes. +- Shared shadcn/ui primitives that remain editable source code. +- Application-level navigation, notifications, chat, and appearance blocks. +- Adapter-based Media and Search packages that do not prescribe a backend. +- A composable Lexical editor package. +- Type-safe application preferences and an internationalization workflow. +- A bilingual MDX documentation site with SSG, search, and Cloudflare deployment. + +## Quick start + +Requirements: + +- [Bun](https://bun.com/) 1.3.5 or newer +- Node.js 22.19 or newer + +Install dependencies and start the example application: + +```sh +bun install +bun run dev ``` -This will place the ui components in the `packages/ui/src/components` directory. +The development server prints the local URL when it is ready. -## Using components +To run the documentation site separately: -To use the components in your app, import them from the `ui` package. +```sh +bun run --cwd docs dev +``` + +## Workspace packages + +The packages are private workspace packages by default. Use them inside this repository with `workspace:*`, or adapt and publish them under your own scope. + +| Package | Use it for | +| --- | --- | +| `@workspace/ui` | Shared components, hooks, icons, design tokens, and global styles | +| `@workspace/blocks` | Application shell, navigation, notifications, chat, and appearance controls | +| `@workspace/media` | Media browsing, uploads, folders, asset selection, and storage adapters | +| `@workspace/search` | Application search, grouped results, pagination, and search history | +| `@workspace/lexical` | Rich-text editing, actions, media nodes, and editor presets | +| `@workspace/i18n` | Locale runtime, catalogs, extraction, compilation, and development tools | +| `@workspace/preferences` | Typed external state, persistence callbacks, SSR snapshots, and effects | + +The intended boundary is simple: your application owns APIs, persistence, routing decisions, and business rules; workspace packages own reusable presentation and interaction behavior. + +## Using a package + +Add a workspace dependency to the consuming application: + +```json +{ + "dependencies": { + "@workspace/media": "workspace:*" + } +} +``` + +Import the package stylesheet once when it provides one. This also lets Tailwind discover the utilities used by that package: + +```css +@import "@workspace/ui/globals.css"; +@import "@workspace/media/globals.css"; +``` + +Then import only the public API you need: ```tsx -import { Button } from "@workspace/ui/components/button"; +import { + MediaLibrary, + MediaProvider, + type MediaAdapter, +} from "@workspace/media" + +export function MediaPage({ adapter }: { adapter: MediaAdapter }) { + return ( + + + + ) +} ``` + +Package-specific setup, adapters, locale catalogs, and progressive examples are documented on the [documentation site](https://react-app-kit.go-slim.dev). + +## Adding shadcn/ui components + +Run the shadcn CLI from the repository root: + +```sh +bunx shadcn@latest add button -c apps/web +``` + +The workspace aliases place generated components in `packages/ui/src/components`. Import them through the UI package: + +```tsx +import { Button } from "@workspace/ui/components/button" +``` + +Generated components belong to the repository and can be changed to match the product instead of being treated as an opaque dependency. + +## Common commands + +| Command | Purpose | +| --- | --- | +| `bun run dev` | Start the example web application | +| `bun run build` | Build the web application | +| `bun run check` | Check formatting, lint, and all workspace types | +| `bun run format` | Format application and package source files | +| `bun run lint` | Run Oxlint across the repository | +| `bun run typecheck` | Type-check every workspace | +| `bun run --cwd packages/media test` | Run tests for one package | +| `bun run --cwd docs build` | Generate the static documentation site | +| `bun run --cwd docs deploy` | Build and deploy the docs to Cloudflare | + +## Project structure + +```text +apps/web/ Runnable TanStack Start application +docs/ Documentation application and SSG pipeline +packages/ + blocks/ Application-level interface blocks + i18n/ Internationalization runtime and tooling + lexical/ Rich-text editor + media/ Media library and picker + preferences/ Typed preference state + search/ Application search + ui/ Shared shadcn/ui components +``` + +Documentation for each package lives beside its source under `packages//docs`, so examples and APIs evolve with the implementation.