gadget-best-practices
Installation
SKILL.md
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