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 · English documentation

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 1.3.5 or newer
• Node.js 22.19 or newer

Install dependencies and start the example application:

bun install
bun run dev

The development server prints the local URL when it is ready.

To run the documentation site separately:

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:

{
  "dependencies": {
    "@workspace/media": "workspace:*"
  }
}

Import the package stylesheet once when it provides one. This also lets Tailwind discover the utilities used by that package:

@import "@workspace/ui/globals.css";
@import "@workspace/media/globals.css";

Then import only the public API you need:

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.

Adding shadcn/ui components

Run the shadcn CLI from the repository root:

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:

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

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.