gadget-best-practices

How to use

This skill provides quick reference patterns and best practices for building with Gadget.

📖 Resources:

• Full documentation: docs.gadget.dev

Read individual rule files for detailed explanations and code examples:

Core Data Modeling

• references/models.md - Data model design patterns and naming conventions
• references/fields.md - Field types, validations, and configuration
• references/relationships.md - Relationship patterns (belongsTo, hasMany, hasManyThrough)
• references/data-access.md - Computed views and computed fields (Gelly aggregates, group by, time-series, access control)

Backend Logic

• references/actions.md - Model actions vs global actions, hooks, and patterns
• references/routes.md - HTTP routes and when to use them vs actions
• references/background-jobs.md - Enqueueing actions and scheduled tasks

Access Control & Security

• references/access-control.md - RBAC, permission filters, and Gelly expressions
• references/shopify-multi-tenancy.md - Shop isolation patterns for Shopify apps

Platform Integrations

• references/shopify-integration.md - Shopify app patterns (webhooks, sync triggers, metafields)
• references/bigcommerce-integration.md - BigCommerce app patterns
• references/webhooks.md - Webhook handling patterns

Frontend Development

• references/frontend-hooks.md - React hooks from @gadgetinc/react
• references/frontend-components.md - Autocomponents and UI patterns
• references/frontend-forms.md - Form handling and validation

Development Workflow

• references/ggt-cli.md - Canonical ggt workflow (sync, checks, logs, envs, conflict handling, parallel worktrees)
• references/testing.md - Framework-agnostic testing setup, scenarios, and CI gates
• references/deployment.md - Deployment workflows and environments
• references/environments.md - Environment variables and multi-environment strategies
• references/project-structure.md - File organization and conventions

API & Authentication

• references/api-client.md - Using the Gadget API client (filters, pagination, relationships)
• references/internal-api.md - Internal API usage, atomic updates, transaction-safe writes, and admin/session context
• references/authentication.md - User authentication patterns
• references/error-codes.md - Common Gadget API error codes, likely causes, and triage workflow