Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aurelienbobenrieth/gadget/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Install the plugin

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

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}
3

Run ESLint

Validate your action files:
eslint .
If you have any validation errors, ESLint will report them with fixable suggestions.
4

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

1

Install the package

Add @aurelienbbn/gadget-ui along with its peer dependencies:
pnpm add @aurelienbbn/gadget-ui react react-dom tailwindcss
2

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",
  ],
};
3

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.
4

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

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.
Ensure you:
  1. Added the Gadget preset to tailwind.config.js
  2. Included the UI package dist folder in your content array
  3. Imported the global styles in your CSS entry point
Run pnpm run build in the UI package if using local development.
Check that:
  1. You imported @aurelienbbn/gadget-ui/styles in your global CSS
  2. Your root HTML element has the data-theme attribute set to “dark” or “light”
  3. Your Tailwind config uses the Gadget preset (not a custom config)

​
Get Help

If you encounter issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us