Quickstart - Gadget Developer Tools

This guide gets you up and running with both the ESLint plugin and UI component library in your Gadget project.

Prerequisites

Before starting, make sure you have:

Node.js 18 or higher
A Gadget project with action files
Basic familiarity with ESLint configuration

ESLint Plugin Setup

Install the plugin

Add @aurelienbbn/eslint-plugin-gadget to your project along with ESLint v9+.

pnpm add -D @aurelienbbn/eslint-plugin-gadget eslint

npm install -D @aurelienbbn/eslint-plugin-gadget eslint

yarn add -D @aurelienbbn/eslint-plugin-gadget eslint

Configure ESLint

Create or update your eslint.config.js with the recommended preset:

eslint.config.js

import gadget from "@aurelienbbn/eslint-plugin-gadget";

export default [
  gadget.configs.recommended,
  // ...your other configs
];

The plugin automatically activates on Gadget action files: **/api/actions/**/*.{js,ts} and **/api/models/**/actions/**/*.{js,ts}

Run ESLint

Validate your action files:

eslint .

If you have any validation errors, ESLint will report them with fixable suggestions.

Fix issues automatically

Many rules support auto-fixing. Run ESLint with the --fix flag:

eslint . --fix

This will automatically fix issues like:

Invalid timeout values (clamped to 900000ms)
Numeric separators in options
Empty onSuccess exports
Missing returnType values

Example: Fixing a validation error

Here’s what you might see when running ESLint on an action file:

api/models/widget/actions/create.ts

import type { ActionOptions } from "gadget-server";

export const options: ActionOptions = {
  timeoutMS: 1_000_000, // Error: exceeds 900000ms
  // Error: returnType must be explicitly set
};

export const run = async () => {
  // action logic
};

After running eslint . --fix, the file is corrected:

api/models/widget/actions/create.ts

import type { ActionOptions } from "gadget-server";

export const options: ActionOptions = {
  timeoutMS: 900000, // 15 minutes
  returnType: true,
};

export const run = async () => {
  // action logic
};

UI Components Setup

Install the package

Add @aurelienbbn/gadget-ui along with its peer dependencies:

pnpm add @aurelienbbn/gadget-ui react react-dom tailwindcss

npm install @aurelienbbn/gadget-ui react react-dom tailwindcss

yarn add @aurelienbbn/gadget-ui react react-dom tailwindcss

Configure Tailwind

Update your tailwind.config.js to use the Gadget preset:

tailwind.config.js

import { gadgetPreset } from "@aurelienbbn/gadget-ui/tailwind-preset";

export default {
  presets: [gadgetPreset],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@aurelienbbn/gadget-ui/dist/**/*.js",
  ],
};

Import global styles

Add the global CSS to your main CSS file or root layout:

styles/globals.css

@import "@aurelienbbn/gadget-ui/styles";

This imports CSS variables for colors, shadows, typography, and theme support.

Use components

Import and use components in your React application:

app/page.tsx

import { Button, Badge, Card, CardHeader, CardTitle, CardContent } from "@aurelienbbn/gadget-ui/components";

export default function Dashboard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome to Gadget</CardTitle>
      </CardHeader>
      <CardContent>
        <Badge variant="accent">New Feature</Badge>
        <Button variant="primary" className="mt-4">
          Get Started
        </Button>
      </CardContent>
    </Card>
  );
}

Example: Theme switching

Toggle between dark and light themes by setting the data-theme attribute on your root element:

app/theme-toggle.tsx

"use client";

import { useState, useEffect } from "react";
import { Button } from "@aurelienbbn/gadget-ui/components";

export function ThemeToggle() {
  const [theme, setTheme] = useState<"dark" | "light">("dark");

  useEffect(() => {
    document.documentElement.setAttribute("data-theme", theme);
  }, [theme]);

  return (
    <Button
      variant="ghost"
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
    >
      {theme === "dark" ? "🌙" : "☀️"}
    </Button>
  );
}

Next Steps

Now that you have both packages installed, explore the documentation:

ESLint Rules

Browse all 16 validation rules organized by category

Component Library

Explore the full component API with examples

Configuration

Learn advanced ESLint configuration options

Design Tokens

Customize colors, typography, and theme behavior

Common Issues

ESLint doesn't validate my action files

Make sure your action files match the expected patterns:

**/api/actions/**/*.{js,ts} for global actions
**/api/models/**/actions/**/*.{js,ts} for model actions

Check your ESLint configuration includes the Gadget plugin config.

Tailwind classes aren't working

Ensure you:

Added the Gadget preset to tailwind.config.js
Included the UI package dist folder in your content array
Imported the global styles in your CSS entry point

Run pnpm run build in the UI package if using local development.

Components don't have proper theming

Check that:

You imported @aurelienbbn/gadget-ui/styles in your global CSS
Your root HTML element has the data-theme attribute set to “dark” or “light”
Your Tailwind config uses the Gadget preset (not a custom config)

Get Help

If you encounter issues:

Check the ESLint Plugin Configuration guide
Review the UI Setup documentation
Open an issue on GitHub

​Prerequisites

​ESLint Plugin Setup

​Example: Fixing a validation error

​UI Components Setup

​Example: Theme switching

​Next Steps

ESLint Rules

Component Library

Configuration

Design Tokens

​Common Issues

​Get Help

Prerequisites

ESLint Plugin Setup

Example: Fixing a validation error

UI Components Setup

Example: Theme switching

Next Steps

Common Issues

Get Help