Getting Started

1. Add the gem

# Gemfile
gem "terrazzo"

bundle install

2. Add the npm package

yarn add terrazzo
# or
npm install terrazzo

The terrazzo npm package is a slim runtime that provides utilities (cn, truncate, formatDate/DateTime/Time), hooks (useIsMobile), and the field registry API. All React components (UI primitives, pages, fields) are copied into your project by the install generator.

3. Install frontend dependencies

The generated components use shadcn/ui patterns, so you'll need these packages:

yarn add @radix-ui/react-avatar @radix-ui/react-dialog @radix-ui/react-dropdown-menu \
  @radix-ui/react-popover @radix-ui/react-separator @radix-ui/react-slot \
  @radix-ui/react-tooltip class-variance-authority clsx lucide-react tailwind-merge

4. Install Superglue (if you haven't already)

Terrazzo is built on top of Superglue. If your app already uses Superglue, skip to step 5.

rails g superglue:install

This sets up the core Superglue infrastructure:

• React/Redux application entry point (app/javascript/application.js)
• Page-to-page mapping, store, and application visit handler
• Flash message Redux slice
• HTML and JSON layouts
• config/initializers/superglue.rb
• JS dependencies (react, react-dom, @reduxjs/toolkit, react-redux, @thoughtbot/superglue)

5. Run the Terrazzo install generator

rails g terrazzo:install

By default the generator assumes Vite. If your app uses esbuild or Sprockets:

rails g terrazzo:install --bundler=esbuild
rails g terrazzo:install --bundler=sprockets

With Vite, the page-to-page mapping uses import.meta.glob to auto-discover React components — custom pages are picked up automatically. With esbuild/Sprockets, the mapping is explicit and the dashboard generator maintains it for you.

This creates an isolated admin namespace alongside your existing app — it won't conflict with any existing Superglue pages or controllers:

Admin Superglue infrastructure (namespaced under admin/):

• app/javascript/admin/application.jsx — separate Superglue entry point for the admin
• app/javascript/admin/page_to_page_mapping.js — maps admin pages to React components (auto-discovered with Vite, explicit with esbuild/Sprockets)
• app/javascript/admin/application_visit.js — visit/remote factory
• app/javascript/admin/slices/flash.js — flash message Redux slice
• app/views/layouts/admin/superglue.html.erb — admin HTML layout
• app/views/layouts/admin/application.json.props — admin JSON props layout

Admin controllers and routes:

• app/controllers/admin/application_controller.rb — inherits from Terrazzo::ApplicationController
• config/routes.rb — adds an admin namespace with a root route

Admin UI components and views:

• app/views/admin/application/ — page views (index, show, new, edit, _form)
• app/views/admin/components/ — shared components (Layout, AppSidebar, SearchBar, etc.)
• app/views/admin/components/ui/ — shadcn UI primitives (Button, Input, Table, etc.)
• app/views/admin/fields/ — field renderers for all 16 field types

Dashboards — automatically generates a dashboard for each ApplicationRecord model it finds.

6. Generate additional dashboards

The install generator (step 5) automatically creates dashboards for all existing ApplicationRecord models. To add dashboards for new models later:

rails g terrazzo:dashboard Product
rails g terrazzo:dashboard Customer
rails g terrazzo:dashboard Order

Each generates:

• app/dashboards/product_dashboard.rb — field definitions
• app/controllers/admin/products_controller.rb — inherits from your admin ApplicationController
• Updates page_to_page_mapping.js with the new resource's pages (esbuild/Sprockets only — Vite auto-discovers them)

7. Start the server

bin/dev

Visit http://localhost:3000/admin to see your admin panel.