supabase-best-practices
Supabase security and performance guidelines with Clerk authentication integration. Contains 40+ rules across 10 categories covering RLS policies, Clerk setup, database security, and more.
- License 许可
- MIT
- 最近更新
- 2026-08-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- supabase-best-practices
- license
- MIT
- metadata
- { "author": "AI Engineering Team", "version": "1.0.1", "last_updated": "2025-01-27" }
- description
- Supabase security and performance guidelines with Clerk authentication integration. Contains 40+ rules across 10 categories covering RLS policies, Clerk setup, database security, and more.
03 SKILL.md 正文
Supabase Best Practices
Comprehensive security and performance optimization guide for Supabase applications with Clerk authentication integration. Contains 40+ rules across 10 categories, prioritized by impact to guide secure development and code review.
When to Apply
Reference these guidelines when:
- Setting up a new Supabase project
- Integrating Clerk authentication with Supabase
- Writing Row Level Security (RLS) policies
- Designing database schemas
- Implementing real-time features
- Configuring Storage buckets
- Writing Edge Functions
- Reviewing code for security issues
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Row Level Security | CRITICAL | rls- |
| 2 | Clerk Integration | CRITICAL | clerk- |
| 3 | Database Security | HIGH | db- |
| 4 | Authentication Patterns | HIGH | auth- |
| 5 | API Security | HIGH | api- |
| 6 | Storage Security | MEDIUM-HIGH | storage- |
| 7 | Realtime Security | MEDIUM | realtime- |
| 8 | Edge Functions | MEDIUM | edge- |
| 9 | Testing | MEDIUM | test- |
| 10 | Security | MEDIUM | security- |
Quick Reference
1. Row Level Security (CRITICAL)
rls-always-enable- Always enable RLS on public schema tablesrls-wrap-functions-select- Wrap auth functions with (SELECT ...) for performancerls-add-indexes- Add indexes on columns used in RLS policiesrls-specify-roles- Specify roles with TO authenticated clauserls-security-definer- Use SECURITY DEFINER functions for complex policiesrls-minimize-joins- Minimize joins in RLS policiesrls-explicit-auth-check- Use explicit auth.uid() checksrls-restrictive-policies- Use RESTRICTIVE policies for additional constraints
2. Clerk Integration (CRITICAL)
clerk-setup-third-party- Use Third-Party Auth integration (not JWT templates)clerk-client-server-side- Use accessToken callback for server-side clientsclerk-client-client-side- Use useSession() hook for client-side clientsclerk-role-claim- Configure role: authenticated claim in Clerkclerk-org-policies- Use organization claims for multi-tenant RLSclerk-mfa-policies- Enforce MFA with RESTRICTIVE policiesclerk-no-jwt-templates- Never use deprecated JWT template integration
3. Database Security (HIGH)
db-migrations-versioned- Use versioned migrations for schema changesdb-schema-design- Follow proper schema design patternsdb-indexes-strategy- Implement proper indexing strategydb-foreign-keys- Always use foreign key constraintsdb-triggers-security- Secure trigger functions properlydb-views-security-invoker- Use SECURITY INVOKER for views
4. Authentication Patterns (HIGH)
auth-jwt-claims-validation- Always validate JWT claimsauth-user-metadata-safety- Treat user_metadata as untrustedauth-app-metadata-authorization- Use app_metadata for authorizationauth-session-management- Implement proper session management
5. API Security (HIGH)
api-filter-queries- Always filter queries even with RLSapi-publishable-keys- Use publishable keys correctlyapi-service-role-server-only- Never expose service role key to client
6. Storage Security (MEDIUM-HIGH)
storage-rls-policies- Enable RLS on storage.objectsstorage-bucket-security- Configure bucket-level securitystorage-signed-urls- Use signed URLs for private files
7. Realtime Security (MEDIUM)
realtime-private-channels- Use private channels for sensitive datarealtime-rls-authorization- RLS policies apply to realtimerealtime-cleanup-subscriptions- Clean up subscriptions on unmount
8. Edge Functions (MEDIUM)
edge-verify-jwt- Always verify JWT in edge functionsedge-cors-handling- Handle CORS properlyedge-secrets-management- Use secrets for sensitive data
9. Testing (MEDIUM)
test-pgtap-rls- Test RLS policies with pgTAPtest-isolation- Isolate tests properlytest-helpers- Use test helper functions
10. Security (MEDIUM)
security-validate-inputs- Validate all inputs before processingsecurity-audit-advisors- Regularly run Security Advisor checks
How to Use
Read individual rule files for detailed explanations and code examples:
references/rules/rls-always-enable.md
references/rules/clerk-setup-third-party.md
references/rules/_sections.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- When NOT to use the pattern
- Reference links to official documentation
Full Compiled Document
For the complete guide with all rules expanded: references/supabase-guidelines.md
04 同仓库更多 Skills
vueuse
Use when working with VueUse composables - provides reactive utilities for state, browser APIs, sensors, network, animations. Check VueUse before writing custom composables - most patterns already implemented.
vue
Use when editing .vue files, creating Vue 3 components, writing composables, or testing Vue code - provides Composition API patterns, props/emits best practices, VueUse integration, and reactive destructuring guidance
vue-best-practices
Vue 3 and Vue.js best practices for TypeScript, vue-tsc, and Volar. This skill should be used when writing, reviewing, or refactoring Vue components to ensure correct typing patterns. Triggers on tasks involving Vue components, props extraction, wrapper components, template type checking, or Volar configuration.
ts-library
Use when authoring TypeScript libraries - covers project setup, package exports, build tooling (tsdown/unbuild), API design patterns, type inference tricks, testing, and release workflows. Patterns extracted from 20+ high-quality ecosystem libraries.
three-best-practices
Three.js performance optimization and best practices guidelines. Use when writing, reviewing, or optimizing Three.js code. Triggers on tasks involving 3D scenes, WebGL/WebGPU rendering, geometries, materials, textures, lighting, shaders, or TSL.
agent-pipeline-builder
Build multi-agent pipelines with structured data flow between agents. Use when creating workflows where each agent has a specialized role and passes output to the next agent.