TableStack

A CLI tool to scaffold production-ready tables using TanStack Table, React, and TypeScript.

TableStack saves you hours of boilerplate by generating fully-featured, type-safe data tables with built-in UI components directly into your project.

Features

•  Instant Setup: Generate complete table architectures in seconds.
• Feature-Rich: Built-in search, pagination, and filtering logic.
• Powered by TanStack: Built on top of the robust @tanstack/react-table.
• Type-Safe: 100% TypeScript with auto-generated types and mocks.
• Reusable Patterns: Extracted hooks and column definitions for clean code.
• Framework Ready: Works seamlessly with Next.js (both app/ and src/app/ directories) and React apps.

Installation

You can install TableStack globally or run it directly using npx:

# Global installation
npm install -g tablestack

# OR run directly via npx
npx tablestack init

Quick Start

1. Initialize the project

Run the init command to set up the base UI components, update your global CSS, and automatically install necessary dependencies.

tablestack init

2. Scaffold a new table

Create a new table feature (e.g., users). This will generate the table component, hooks, column definitions, and mock data.

tablestack add users

3. Scaffold with specific columns

You can define your schema right from the CLI to automatically generate the correct TypeScript interfaces and UI columns.

tablestack add users --columns "id:string,name:string,email:string,status:badge"

CLI Commands

| | | | | ------------ | ---------------------- | ------------------------------------------------------------------------------------------ | | Command | Options | Description | | init |   | Initializes TableStack, copies base UI components, updates CSS, and installs dependencies. | | add <name> | --columns "<schema>" | Generates a new table with the specified name and optional schema. | |   | --force | Overwrites existing table files if they already exist. |

Supported Column Types

When using the --columns flag, you can specify the following data types:

| | | | | -------- | -------------------------- | ---------------- | | Type | Description | Example | | string | Standard text content | name:string | | number | Numeric values | age:number | | date | Formatted date strings | createdAt:date | | badge | Visual status UI component | status:badge |

Generated Structure

When you add a new table (e.g., users), TableStack generates a clean, modular file structure:

src/
└── components/
    └── tables/
        └── users/
            ├── users-table.tsx       # Main table component
            ├── use-users.ts          # State and logic hook
            ├── use-users-columns.tsx # Column definitions
            ├── users.types.ts        # TypeScript interfaces
            └── users.mock.ts         # Sample data for testing

Usage Example

Once generated, simply import the table component into your page or view:

import UsersTable from "@/components/tables/users/users-table";

export default function UsersPage() {
  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-6">User Management</h1>
      <UsersTable />
    </main>
  );
}

Dependencies

TableStack automatically installs the following dependencies during the init process based on your package manager (npm, yarn, pnpm, or bun):

• @tanstack/react-table
• lucide-react (for icons)
• clsx & tailwind-merge (for dynamic classes)
• class-variance-authority (for UI variants)
• @radix-ui/react-select, @radix-ui/react-label, @radix-ui/react-slot (for accessible UI primitives)

Notes

• CSS Handling: The init command safely prompts you before modifying your existing globals.css. You can choose to append to it, replace it, or create a separate tablestack.css file.
• Idempotent: It is safe to re-run tablestack init; it will not overwrite your files destructively without prompting.
• Smart Paths: TableStack automatically detects whether you are using a src/ directory or working directly in the root (common in Next.js).

Development

To run the CLI locally during development:

# Run compiled JS
node bin/index.js init

# OR run TypeScript directly using tsx
npx tsx src/bin/index.ts init

👤 Author

Aravind Vijayan

License

MIT