https://github.com/joseph0926/firsttx
FirstTx · Prepaint + Local-First + Tx toolkit for instant CSR revisits, offline durability, and atomic optimistic updates.
https://github.com/joseph0926/firsttx
client-side-rendering indexeddb optimistic-ui pre-rendering react transaction undo-redo
Last synced: 2 months ago
JSON representation
FirstTx · Prepaint + Local-First + Tx toolkit for instant CSR revisits, offline durability, and atomic optimistic updates.
- Host: GitHub
- URL: https://github.com/joseph0926/firsttx
- Owner: joseph0926
- License: mit
- Created: 2025-10-04T00:01:34.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-21T01:13:00.000Z (2 months ago)
- Last Synced: 2026-02-21T07:14:24.701Z (2 months ago)
- Topics: client-side-rendering, indexeddb, optimistic-ui, pre-rendering, react, transaction, undo-redo
- Language: TypeScript
- Homepage: https://www.firsttx.store
- Size: 2.7 MB
- Stars: 10
- Watchers: 0
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Governance: GOVERNANCE.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# FirstTx
[](https://scorecard.dev/viewer/?uri=github.com/joseph0926/firsttx)
[](https://opensource.org/licenses/MIT)
[Docs](https://www.firsttx.store) | [Playground](https://firsttx-playground.vercel.app) | [DevTools](https://chromewebstore.google.com/detail/firsttx-devtools/onpdifkipmmkajdhodmpphmlpbnopkdd)
> 한국어 버전은 [docs/README.ko.md](./docs/README.ko.md)를 확인해주세요.
**Eliminate blank screens on revisits - Restore last state instantly**
## TL;DR
FirstTx elevates CSR app revisit experience to SSR-level:
- **Prepaint**: Instantly restore last screen before JS loads (0ms blank screen)
- **Local-First**: Auto-sync IndexedDB + React (data persists on refresh)
- **Tx**: Optimistic updates + auto-rollback (safe even on failure)
## Demo
Before
After
Slow 4G: Blank screen
Slow 4G: Instant restore
> See all demos in [Playground](https://firsttx-playground.vercel.app)
## Why FirstTx?
Traditional solutions for revisit UX (SSR/SSG) add infrastructure complexity. Manual IndexedDB requires 500+ lines of boilerplate. FirstTx provides SSR-level UX while keeping CSR architecture simple.
## Installation
```bash
pnpm add @firsttx/prepaint @firsttx/local-first @firsttx/tx
```
Partial installation
- Revisit only: `pnpm add @firsttx/prepaint`
- Revisit + Sync: `pnpm add @firsttx/prepaint @firsttx/local-first`
- Sync + Tx: `pnpm add @firsttx/local-first @firsttx/tx`
> Tx requires Local-First as a dependency.
> ESM-only. For CommonJS, use dynamic `import()`.
## Quick Start
### 1. Vite Plugin
```ts
// vite.config.ts
import { firstTx } from '@firsttx/prepaint/plugin/vite';
export default defineConfig({
plugins: [firstTx()],
});
```
### 2. Entry Point
```tsx
// main.tsx
import { createFirstTxRoot } from '@firsttx/prepaint';
createFirstTxRoot(document.getElementById('root')!, );
```
### 3. Use in Component
```tsx
import { useSyncedModel } from '@firsttx/local-first';
function CartPage() {
const { data: cart } = useSyncedModel(CartModel, () => fetch('/api/cart').then((r) => r.json()));
if (!cart) return ;
return ;
}
```
> For optimistic updates with Tx, see [API Reference](./docs/API.md#tx).
## When to Use
| Use FirstTx | Consider Alternatives |
| -------------------------------- | ------------------------------------------ |
| Internal tools (CRM, dashboards) | Public landing pages → SSR/SSG |
| Frequent revisits (10+/day) | First-visit performance critical → SSR |
| No SEO requirements | Always need latest data → Server-driven UI |
## Browser Support
| Browser | Min Version | ViewTransition |
| ----------- | ----------- | ----------------- |
| Chrome/Edge | 111+ | Full |
| Firefox | Latest | Graceful fallback |
| Safari | 16+ | Graceful fallback |
## Troubleshooting
**UI duplicates on refresh**: Enable `overlay: true` in Vite plugin.
**Hydration warnings**: Add `data-firsttx-volatile` to frequently changing elements.
**TypeScript errors**: Add `declare const __FIRSTTX_DEV__: boolean`.
More at [GitHub Issues](https://github.com/joseph0926/firsttx/issues).
## Links
- [API Reference](./docs/API.md)
- [Playground](https://firsttx-playground.vercel.app)
- [DevTools](https://chromewebstore.google.com/detail/firsttx-devtools/onpdifkipmmkajdhodmpphmlpbnopkdd)
- [GitHub](https://github.com/joseph0926/firsttx)
- [Issues](https://github.com/joseph0926/firsttx/issues)
## License
MIT © [joseph0926](https://github.com/joseph0926)