tben
73a25f54c2
Runs at http://localhost:7010 via bun run dev. The playground imports the library from src through a committed symlink and tsconfig path alias, so component edits hot-reload without a build step. It has its own install root and is excluded from the published package.
109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
# @moduletrace/twui
|
|
|
|
A modular skeletal React component framework for Tailwind CSS v4.
|
|
|
|
## Install
|
|
|
|
The package is published to the Moduletrace Gitea registry. Add this to your project's `.npmrc`:
|
|
|
|
```ini
|
|
@moduletrace:registry=https://git.tben.me/api/packages/moduletrace/npm/
|
|
```
|
|
|
|
Then install the package with its required peers:
|
|
|
|
```sh
|
|
bun add @moduletrace/twui react react-dom lucide-react tailwindcss
|
|
```
|
|
|
|
### Optional peers
|
|
|
|
Only install these if you use the matching components:
|
|
|
|
| Feature | Packages |
|
|
| ------------------------------------------------------- | ------------------------------------------------ |
|
|
| `editors/AceEditor` | `ace-builds` |
|
|
| `elements/RemoteCodeBlock`, `mdx/markdown/*` | `next-mdx-remote`, `remark-gfm`, `rehype-prism-plus` |
|
|
| `mdx/mdx-components`, `next-js/hooks/useMDXComponents` | `@types/mdx` (dev) |
|
|
| `elements/ai/*` | `openai` (types), `react-markdown` |
|
|
|
|
`editors/TinyMCE` loads TinyMCE from a URL at runtime. Set it with the `base_url` prop, or with the `NEXT_PUBLIC_TINYMCE_BASE_URL` / `BUNEXT_PUBLIC_TINYMCE_BASE_URL` public env vars.
|
|
|
|
## CSS
|
|
|
|
Import `base.css` once in your main stylesheet. It includes `@import "tailwindcss"`, the default theme tokens, and an `@source` rule so Tailwind generates the classes the components use. Override tokens in your own `@theme inline` block:
|
|
|
|
```css
|
|
@import "@moduletrace/twui/base.css";
|
|
|
|
@theme inline {
|
|
--color-primary: #e2b433;
|
|
--color-primary-hover: #9e7503;
|
|
--color-primary-dark: #e2b433;
|
|
--color-primary-dark-hover: #f7cc59;
|
|
/* ...see base.css for the full list of tokens */
|
|
}
|
|
|
|
.twui-button-general {
|
|
@apply rounded-full;
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
Import from the root entry:
|
|
|
|
```tsx
|
|
import { Button, Stack, Row, useStatus } from "@moduletrace/twui";
|
|
```
|
|
|
|
Or use deep imports, which mirror the source folder layout:
|
|
|
|
```tsx
|
|
import Button from "@moduletrace/twui/layout/Button";
|
|
import Input from "@moduletrace/twui/form/Input";
|
|
import TinyMCEEditor from "@moduletrace/twui/editors/TinyMCE";
|
|
```
|
|
|
|
Editors, MDX, Next.js helpers, the AI blocks and `RemoteCodeBlock` are **deep-import only**, so the root entry never pulls in optional peers.
|
|
|
|
Component modules are marked `"use client"`, so they work in the Next.js App Router.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
bun install
|
|
bun run typecheck
|
|
bun test src
|
|
bun run compile # tsc → dist/, then scripts/post-compile.ts
|
|
```
|
|
|
|
### Playground
|
|
|
|
`dev/` is a local [bunext](https://git.tben.me/Moduletrace/bunext) app that imports the library straight from `src/` (through the committed `dev/twui` symlink and a tsconfig path alias), so component edits hot-reload without running `tsc`. It has its own `node_modules` and is excluded from the published package by the `files` whitelist.
|
|
|
|
```sh
|
|
cd dev
|
|
bun install
|
|
cd ..
|
|
bun run dev # http://localhost:7010
|
|
```
|
|
|
|
Install the library dependencies at the repo root first: the symlinked sources resolve `react`, `tailwind-merge`, `lucide-react` and the optional peers from the root `node_modules`.
|
|
|
|
Other useful scripts:
|
|
|
|
```sh
|
|
bun run dev:types # tsc --watch, for consumers working against dist/
|
|
bun run dev:typecheck # typecheck the playground pages and the sources they import
|
|
```
|
|
|
|
### Publishing
|
|
|
|
```sh
|
|
export GITBEN_NPM_TOKEN=...
|
|
./publish.sh "Commit message"
|
|
```
|
|
|
|
`publish.sh` typechecks, tests, compiles, commits, pushes, and runs `bun publish`. Bump `version` in `package.json` first.
|