Maofeng
140 lines
4.8 KiB
Markdown
140 lines
4.8 KiB
Markdown
# Simple React App Kit
|
|
|
|
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.
|
|
|
|
[Open the documentation](https://react-app-kit.go-slim.dev) · [English documentation](https://react-app-kit.go-slim.dev/en-US/)
|
|
|
|
## What you get
|
|
|
|
- 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
|
|
```
|
|
|
|
The development server prints the local URL when it is ready.
|
|
|
|
To run the documentation site separately:
|
|
|
|
```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 {
|
|
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.
|