Skip to content

Commit 25025ae

Browse files
jacekradkojacekradko
authored
chore(repo): Shared Cursor rules (#6092)
1 parent 97749d5 commit 25025ae

File tree

7 files changed

+912
-0
lines changed

7 files changed

+912
-0
lines changed

‎.changeset/honest-cougars-bet.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
---

‎.cursor/rules/development.mdc

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
Development Practices and Tooling
7+
8+
Development Environment Setup
9+
- Requires Node.js 18.17.0+ and pnpm 9.15.9+
10+
- Use `pnpm install` to install all dependencies
11+
- Environment variables should be set in appropriate `.env` files
12+
- Use `pnpm dev` to start development mode across all packages
13+
14+
Monorepo Development Workflow
15+
- Make changes in the relevant package under `/packages/`
16+
- Use `pnpm dev` to watch for changes and rebuild automatically
17+
- Test changes using playground applications in `/playground/`
18+
- Run specific package commands using pnpm workspace syntax: `pnpm --filter @clerk/nextjs build`
19+
- Use Turbo for efficient builds: `turbo build --filter=@clerk/nextjs`
20+
21+
Code Quality Standards
22+
- All code must pass ESLint checks with the project's configuration
23+
- Use Prettier for consistent code formatting
24+
- TypeScript is required for all packages
25+
- Follow established naming conventions (PascalCase for components, camelCase for variables)
26+
- Maintain comprehensive JSDoc comments for public APIs
27+
28+
Testing Requirements
29+
- Unit tests are required for all new functionality
30+
- Use Jest for unit testing, Vitest for some packages
31+
- React Testing Library for component testing
32+
- Integration tests using Playwright for E2E scenarios
33+
- Test files should be co-located with source files or in `__tests__` directories
34+
- Maintain test coverage above established thresholds
35+
36+
Package Development Guidelines
37+
- Each package should have a clear single responsibility
38+
- Follow semantic versioning for all packages
39+
- Use Changesets for version management and changelogs
40+
- Packages should export TypeScript types alongside runtime code
41+
- Use tsup for building packages with proper ESM/CJS dual publishing
42+
43+
Framework Integration Patterns
44+
- Framework packages should provide idiomatic APIs for their respective frameworks
45+
- Maintain consistency in naming and patterns across framework integrations
46+
- Provide both high-level components and low-level utilities
47+
- Ensure SSR/SSG compatibility where applicable
48+
- Follow framework-specific best practices and conventions
49+
50+
API Design Principles
51+
- Design APIs to be intuitive and self-documenting
52+
- Provide sensible defaults to minimize configuration
53+
- Support both imperative and declarative usage patterns
54+
- Maintain backward compatibility when possible
55+
- Use progressive enhancement for advanced features
56+
57+
Build and Bundle Optimization
58+
- Use tree-shaking friendly exports
59+
- Minimize bundle sizes through careful dependency management
60+
- Use dynamic imports for optional features
61+
- Monitor bundle sizes with bundlewatch
62+
- Optimize for both development and production builds
63+
64+
Documentation Standards
65+
- All public APIs must be documented with JSDoc
66+
- Provide usage examples in documentation
67+
- Maintain up-to-date README files for each package
68+
- Use TypeDoc for generating API documentation
69+
- Include migration guides for breaking changes
70+
71+
Error Handling Patterns
72+
- Use proper TypeScript error types
73+
- Provide meaningful error messages to developers
74+
- Include error recovery suggestions where applicable
75+
- Log errors appropriately for debugging
76+
- Use error boundaries in React components
77+
78+
Performance Considerations
79+
- Lazy load components and features when possible
80+
- Implement proper caching strategies
81+
- Minimize re-renders in React components
82+
- Use efficient data structures and algorithms
83+
- Profile and optimize critical paths
84+
85+
Security Guidelines
86+
- Never commit sensitive keys or credentials
87+
- Use environment variables for configuration
88+
- Validate all inputs and sanitize outputs
89+
- Follow OWASP security best practices
90+
- Regular security audits of dependencies
91+
92+
Debugging and Development Tools
93+
- Use browser dev tools for client-side debugging
94+
- Implement proper logging with different levels
95+
- Use Clerk's development dashboard for testing
96+
- Leverage source maps for debugging built code
97+
- Use performance profiling tools when needed
98+
99+
Integration Testing Approach
100+
- Each framework integration has its own test suite
101+
- Use real Clerk instances for integration tests
102+
- Test authentication flows end-to-end
103+
- Verify proper error handling and edge cases
104+
- Test across different browsers and environments
105+
106+
Release Process
107+
- Use Changesets for managing releases
108+
- Follow semantic versioning strictly
109+
- Coordinate releases across dependent packages
110+
- Test releases in staging environments
111+
- Maintain detailed changelogs
112+
113+
Local Development Tips
114+
- Use playground applications to test changes quickly
115+
- Set up multiple test environments for different scenarios
116+
- Use Verdaccio for local npm registry testing
117+
- Leverage hot reloading for faster development cycles
118+
- Use proper IDE setup with TypeScript support
119+
120+
Contribution Guidelines
121+
- Follow the established PR template
122+
- Include tests for all new features
123+
- Update documentation for API changes
124+
- Ensure all CI checks pass before merging
125+
- Get proper code review from team members
126+
127+
Package Maintenance
128+
- Regularly update dependencies
129+
- Monitor for security vulnerabilities
130+
- Deprecate features properly with migration paths
131+
- Maintain compatibility matrices for supported versions
132+
- Archive packages that are no longer maintained

‎.cursor/rules/global.mdc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
Clerk JavaScript SDK Monorepo
7+
8+
1. Package Manager
9+
- This project is a monorepo that uses pnpm
10+
- Turbo is used for build orchestration and caching
11+
- Node.js is required
12+
13+
2. Repository Overview
14+
- All packages published under @clerk namespace
15+
- Supports 10+ JavaScript frameworks and platforms
16+
- Comprehensive testing with unit, integration, and E2E tests
17+
18+
3. Key Directories
19+
- `packages/` - All publishable packages (@clerk/*)
20+
- `integration/` - Framework integration templates and E2E tests
21+
- `playground/` - Development and testing applications
22+
- `scripts/` - Build automation and utilities
23+
- `.cursor/rules/` - Additional rule files for specific domains
24+
25+
4. Core Commands
26+
- `pnpm dev` - Start development mode for all packages
27+
- `pnpm build` - Build all packages
28+
- `pnpm test` - Run unit tests
29+
- `pnpm test:integration:*` - Framework-specific integration tests
30+
- `pnpm lint` - Lint all packages
31+
- `pnpm format` - Format code with Prettier
32+
33+
5. Development Workflow
34+
- Make changes in relevant package under packages/
35+
- Use playground apps for testing changes
36+
- Follow established testing and documentation requirements
37+
- Use Changesets for version management and releases

‎.cursor/rules/monorepo.mdc

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
Monorepo Architecture and Structure
7+
8+
Repository Overview
9+
- This is the official Clerk JavaScript SDK monorepo containing all Clerk authentication packages
10+
- Clerk provides streamlined user experiences for sign up, sign in, and profile management
11+
- All packages are published under the @clerk namespace on npm
12+
- Uses pnpm as the package manager with Turbo for build orchestration
13+
- Supports multiple JavaScript frameworks and environments
14+
15+
Core Package Categories
16+
- **Core SDK**: `@clerk/clerk-js` - Core browser SDK with UI components
17+
- **Framework Integrations**: Next.js, React, Vue, Astro, Nuxt, Remix, Express, Fastify
18+
- **Platform Support**: Expo (React Native), Chrome Extension
19+
- **Backend**: `@clerk/backend` - Server-side utilities and JWT verification
20+
- **Shared Utilities**: `@clerk/shared`, `@clerk/types` - Common utilities and TypeScript types
21+
- **Developer Tools**: `@clerk/testing`, `@clerk/dev-cli`, `@clerk/upgrade`
22+
- **UI Libraries**: `@clerk/elements` - Unstyled UI primitives, `@clerk/themes` - Pre-built themes
23+
- **Specialized**: `@clerk/agent-toolkit` - AI agent integration tools
24+
25+
Directory Structure
26+
- `packages/` - All publishable packages
27+
- `integration/` - End-to-end tests and integration templates
28+
- `playground/` - Development and testing applications
29+
- `docs/` - Documentation and contribution guides
30+
- `scripts/` - Build and automation scripts
31+
- `tools/` - Internal development tools
32+
33+
Development Workflow
34+
- Use `pnpm dev` to start development mode for all packages
35+
- Use `pnpm build` to build all packages
36+
- Use `pnpm test` to run unit tests across all packages
37+
- Use `pnpm test:integration:*` for framework-specific integration tests
38+
- Turbo handles caching and dependency orchestration
39+
- Changesets for version management and release automation
40+
41+
Framework-Specific Packages
42+
- `@clerk/nextjs` - Next.js App Router and Pages Router support
43+
- `@clerk/clerk-react` - React hooks and components
44+
- `@clerk/vue` - Vue.js composables and components
45+
- `@clerk/astro` - Astro integration with SSR support
46+
- `@clerk/nuxt` - Nuxt.js module
47+
- `@clerk/remix` - Remix loader and action utilities
48+
- `@clerk/express` - Express.js middleware
49+
- `@clerk/fastify` - Fastify plugin
50+
- `@clerk/expo` - React Native/Expo SDK
51+
52+
Testing Architecture
53+
- Unit tests with Jest and Vitest
54+
- Integration tests with Playwright
55+
- Component testing with React Testing Library
56+
- End-to-end tests across multiple framework templates
57+
- Visual regression testing for UI components
58+
- Separate test configurations per framework
59+
60+
Build System
61+
- Turbo for monorepo orchestration and caching
62+
- tsup for TypeScript compilation and bundling
63+
- ESLint with custom configurations for different package types
64+
- Prettier for code formatting
65+
- Bundle size monitoring with bundlewatch
66+
- Type checking with TypeScript and publint
67+
68+
Environment Configuration
69+
- Supports multiple Clerk environment variables (CLERK_*, NEXT_PUBLIC_CLERK_*, etc.)
70+
- Development, staging, and production configurations
71+
- Verdaccio for local npm registry testing
72+
- Docker support for integration testing
73+
- CI/CD with GitHub Actions
74+
75+
Localization Support
76+
- `packages/localizations/` contains translations for 30+ languages
77+
- Modular localization system allowing partial imports
78+
- Support for RTL languages
79+
- Framework-agnostic translation utilities
80+
81+
Package Interdependency Rules
82+
- `@clerk/shared` is a common dependency for most packages
83+
- `@clerk/types` provides TypeScript definitions used across packages
84+
- `@clerk/backend` is independent and used for server-side operations
85+
- Framework packages depend on `@clerk/clerk-js` for core functionality
86+
- Integration packages build upon framework-specific packages
87+
88+
Release Management
89+
- Automated releases with Changesets
90+
- Semantic versioning across all packages
91+
- Canary and snapshot releases for testing
92+
- Git tags and GitHub releases for version tracking
93+
- Coordinated releases to maintain compatibility between packages

0 commit comments

Comments
 (0)