docs: rewrite project readme
This commit is contained in:
Maofeng
@@ -1,22 +1,139 @@
|
|||||||
# Simple React App Kit
|
# Simple React App Kit
|
||||||
|
|
||||||
Simple React App Kit is a reusable React application kit built with TanStack
|
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.
|
||||||
Start, shadcn/ui, and workspace packages.
|
|
||||||
|
|
||||||
## 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
|
- A TanStack Start application with routing, SSR, responsive layout, and light/dark themes.
|
||||||
pnpm dlx shadcn@latest add button -c apps/web
|
- 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
|
```tsx
|
||||||
import { Button } from "@workspace/ui/components/button";
|
import {
|
||||||
|
MediaLibrary,
|
||||||
|
MediaProvider,
|
||||||
|
type MediaAdapter,
|
||||||
|
} from "@workspace/media"
|
||||||
|
|
||||||
|
export function MediaPage({ adapter }: { adapter: MediaAdapter }) {
|
||||||
|
return (
|
||||||
|
<MediaProvider adapter={adapter}>
|
||||||
|
<MediaLibrary />
|
||||||
|
</MediaProvider>
|
||||||
|
)
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
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/<name>/docs`, so examples and APIs evolve with the implementation.
|
||||||
|
|||||||
Reference in New Issue
Block a user