simple-react-app-kit/README.md

# 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.