Skip to content

Commit 48cacce

Browse files
nrkruknrkruk
authored
chore: update build task and add cursor rules for repo @W-18979277 (#458)
* chore: update task label and arguments in tasks.json for CLI plugin build * feat: add comprehensive cursor rules documentation for Salesforce CLI plugin * docs: update project overview and cleanup instructions in cursor rules documentation
1 parent 75fa8b7 commit 48cacce

File tree

2 files changed

+193
-2
lines changed

2 files changed

+193
-2
lines changed

‎.cursorrules

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Salesforce CLI Plugin Lightning Dev - Cursor Rules
2+
3+
## Project Overview
4+
5+
This is a Salesforce CLI plugin for Lightning Web Component development (LEX, Mobile, Experience Sites, and Single Component Preview). It's built with TypeScript, uses yarn for package management, and leverages wireit for intelligent build caching and task orchestration.
6+
7+
## Key Technologies
8+
9+
- **TypeScript**: Primary language for the plugin
10+
- **Wireit**: Build task orchestration with intelligent caching
11+
- **Yarn**: Package manager (v1.22.22 as specified in volta config)
12+
- **Node.js**: This project supports all active and LTS versions of node
13+
- **Salesforce CLI (sf)**: The platform this plugin extends
14+
- **Lightning Web Components (LWC)**: Core technology for component development
15+
- **Jest/Mocha**: Testing frameworks
16+
17+
## Understanding Wireit Caching
18+
19+
### What is Wireit?
20+
21+
Wireit is a build orchestration tool that provides:
22+
23+
- **Incremental builds**: Only rebuilds what has changed
24+
- **Intelligent caching**: Stores build outputs in `.wireit/` directory
25+
- **Task dependencies**: Automatically runs dependent tasks in correct order
26+
- **Parallel execution**: Runs independent tasks concurrently
27+
28+
### Wireit Cache Location
29+
30+
- Cache is stored in `.wireit/` directory at the project root
31+
- Contains fingerprints and outputs from previous builds
32+
- Can become corrupted or inconsistent, leading to build errors
33+
34+
### Common Wireit Tasks in This Project
35+
36+
- `build`: Main build task (depends on compile + lint)
37+
- `compile`: TypeScript compilation with incremental builds
38+
- `lint`: ESLint with caching
39+
- `test`: Comprehensive testing including unit tests, command reference, deprecation policy
40+
- `format`: Prettier formatting
41+
42+
## Troubleshooting Build Issues
43+
44+
### When to Run `clean-all`
45+
46+
Run `yarn clean-all` when experiencing:
47+
48+
- **Mysterious TypeScript errors** that don't match the actual code
49+
- **Outdated build outputs** not reflecting recent changes
50+
- **Wireit dependency errors** or inconsistent cache states
51+
- **"Cannot find module" errors** for modules that clearly exist
52+
- **Incremental builds failing** but full rebuilds work
53+
- **Test failures** that don't reproduce when running tests individually
54+
- **Linting errors** on unchanged files
55+
56+
### The `clean-all` Process
57+
58+
```bash
59+
# This command cleans ALL build artifacts and caches
60+
yarn clean-all
61+
```
62+
63+
What `clean-all` does:
64+
65+
- Runs `sf-clean all` which removes:
66+
- `lib/` directory (compiled output)
67+
- `.wireit/` directory (all cached tasks and fingerprints)
68+
- `*.tsbuildinfo` files (TypeScript incremental compilation cache)
69+
- `.eslintcache` file (ESLint cache)
70+
- Other temporary build artifacts
71+
72+
### Post-Cleanup Setup
73+
74+
**CRITICAL**: After running `clean-all`, you must re-setup the environment:
75+
76+
```bash
77+
# Always run these commands after clean-all
78+
yarn install && yarn build
79+
```
80+
81+
Why both commands are needed:
82+
83+
1. `yarn install`: Ensures all dependencies are properly installed and linked
84+
2. `yarn build`: Rebuilds all artifacts and re-populates wireit cache
85+
86+
### Alternative Cleaning Options
87+
88+
- `yarn clean`: Light cleanup (preserves some caches)
89+
- Individual task clearing: Delete specific folders in `.wireit/` or `.eslintcache` if you know which task is problematic
90+
91+
## Development Workflow Best Practices
92+
93+
### Starting Development
94+
95+
```bash
96+
# Fresh start (if needed)
97+
yarn clean-all
98+
yarn install && yarn build
99+
100+
# Normal development
101+
yarn build # Builds incrementally using wireit cache
102+
```
103+
104+
### Running Tests
105+
106+
```bash
107+
yarn test # Full test suite with all checks
108+
yarn test:only # Just unit tests
109+
yarn test:nuts # Integration tests (slower)
110+
```
111+
112+
### Linking for Testing
113+
114+
```bash
115+
# Link plugin to global sf CLI for testing
116+
sf plugins link .
117+
```
118+
119+
## Project-Specific Context
120+
121+
### Lightning Development Commands
122+
123+
This plugin provides three main commands:
124+
125+
- `sf lightning dev component`: Preview LWC components locally
126+
- `sf lightning dev site`: Preview Experience Cloud sites locally
127+
- `sf lightning dev app`: Preview Lightning apps locally
128+
129+
### LWR (Lightning Web Runtime) Integration
130+
131+
- Uses LWR for server-side rendering and local development
132+
- Has special yarn scripts for linking/unlinking LWR dependencies
133+
- `__lwr_cache__/` directory stores LWR-specific cache
134+
135+
### API Version Management
136+
137+
- Supports multiple Salesforce API versions (62.0-65.0)
138+
- Has version mappings in `apiVersionMetadata` in package.json
139+
- Different tags target different org versions
140+
141+
## File Structure Understanding
142+
143+
### Key Directories
144+
145+
- `src/`: Source TypeScript files
146+
- `lib/`: Compiled JavaScript output (generated)
147+
- `test/`: All test files (.test.ts, .nut.ts)
148+
- `messages/`: CLI command help text and internationalization
149+
- `.wireit/`: Build cache (can be safely deleted)
150+
151+
### Important Files
152+
153+
- `package.json`: Contains all wireit task definitions
154+
- `tsconfig.json`: TypeScript configuration
155+
- `lwc.config.json`: Lightning Web Components configuration
156+
- `.eslintcache`: ESLint cache file (can be safely deleted)
157+
158+
## Coding Guidelines
159+
160+
### TypeScript Standards
161+
162+
- Use strict TypeScript compilation settings
163+
- Follow Salesforce coding standards
164+
- Prefer explicit types over `any`
165+
- Use proper JSDoc comments for CLI commands
166+
167+
### Testing Requirements
168+
169+
- Unit tests for all new functionality
170+
- Integration tests (nuts) for CLI commands
171+
- Minimum 95% code coverage requirement
172+
- Mock external dependencies appropriately
173+
174+
### CLI Command Development
175+
176+
- Follow oclif patterns for command structure
177+
- Use proper message files for user-facing text
178+
- Include comprehensive help text and examples
179+
- Handle errors gracefully with user-friendly messages
180+
181+
## Common Pitfalls to Avoid
182+
183+
1. **Don't commit build artifacts**: `lib/` directory should never be committed
184+
2. **Don't ignore wireit cache issues**: If builds seem wrong, clean and rebuild
185+
3. **Don't skip the yarn install step**: After `clean-all`, always reinstall dependencies
186+
4. **Don't modify generated files**: Focus changes on `src/` directory
187+
5. **Don't ignore eslint cache issues**: If linting shouldn't be failing, always try deleting the `.eslintcache`
188+
189+
## Emergency Troubleshooting
190+
191+
Remember: **When in doubt, `yarn clean-all && yarn install && yarn build`** - this solves 90% of build-related issues in this project.

‎.vscode/tasks.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"problemMatcher": "$tsc",
44
"tasks": [
55
{
6-
"label": "Compile tests",
6+
"label": "Build CLI Plugin",
77
"group": {
88
"kind": "build",
99
"isDefault": true
@@ -14,7 +14,7 @@
1414
"focus": false,
1515
"panel": "dedicated"
1616
},
17-
"args": ["test:compile"],
17+
"args": ["build"],
1818
"isBackground": false
1919
}
2020
]

0 commit comments

Comments
 (0)