Windsurf Global Rules

A comprehensive npm package that provides global rules and workspace configuration for Windsurf IDE to ensure consistent code quality across all your JavaScript/TypeScript projects.

🌊 Features

• Global Rules: Comprehensive set of ESLint rules optimized for Windsurf IDE
• Workspace Configuration: Automatic workspace setup with environment-specific rules
• Framework Support: Built-in configurations for React, Node.js, Vue, and more
• Git Hooks: Automatic pre-commit hooks for rule enforcement
• Auto-fix: Many rules support automatic fixing
• Environment Awareness: Different rule sets for development, test, and production

📦 Installation

Global Installation (Recommended)

npm install -g windsurf-global-rules

Project-specific Installation

npm install --save-dev windsurf-global-rules

🚀 Quick Start

Automatic Setup

After installation, the package will automatically run the setup process:

# This runs automatically after npm install
npm run setup

Or run it manually:

npx windsurf-setup

Manual Application

Apply rules to any project directory:

npx windsurf-apply-rules [directory]

📋 Usage

1. Basic Setup

The setup process will ask you a few questions:

• Environment: Development, Test, or Production
• Framework: React, Node.js, Vue, or None
• ESLint Config: Whether to create/update ESLint configuration
• Git Hooks: Whether to set up pre-commit hooks

2. Running Lints

After setup, you can use these commands:

# Check your code
npm run lint

# Auto-fix issues
npm run lint:fix

# Or use ESLint directly
npx eslint .
npx eslint . --fix

3. Programmatic Usage

const WindsurfRules = require('windsurf-global-rules');

// Create instance
const rules = new WindsurfRules();

// Apply rules to a directory
await rules.applyRules('./my-project', {
  environment: 'production',
  framework: 'react',
  createEslintConfig: true,
  createGitHooks: true
});

// Get ESLint configuration
const eslintConfig = rules.getESLintConfig();

// Get workspace rules
const workspaceRules = rules.getWorkspaceRules();

// Validate existing setup
const validation = await rules.validateRules('./my-project');

🛠️ Configuration

Environment-Specific Rules

Development Environment

• Allows console.log (warning level)
• Allows debugger statements (warning level)
• Relaxed complexity rules

Test Environment

• Allows console.log for test output
• Allows magic numbers in test assertions
• Relaxed file length limits

Production Environment

• Strict enforcement of all rules
• No console statements allowed
• No debugger statements allowed

Framework-Specific Rules

React

• JSX-specific rules
• PropTypes validation
• Component lifecycle rules

Node.js

• No synchronous methods
• Process exit restrictions
• Buffer and stream optimizations

Vue

• Template syntax rules
• Component structure validation
• Directive usage guidelines

📁 Generated Files

After running the setup, these files will be created in your project:

.eslintrc.js

ESLint configuration with Windsurf global rules applied.

.windsurf-rules.json

Workspace-specific configuration file containing:

• Selected environment settings
• Framework-specific rules
• Custom rule overrides

.git/hooks/pre-commit

Git pre-commit hook that runs ESLint before each commit.

🎯 Available Rules

Code Quality Rules

| Rule | Level | Auto-fix | Description | |------|-------|----------|-------------| | no-console | Error/Warning | ✅ | Prevents console statements in production | | no-debugger | Error/Warning | ✅ | Prevents debugger statements in production | | no-unused-vars | Warning | ❌ | Removes unused variables | | prefer-const | Warning | ✅ | Enforces const for non-reassigned variables |

Style Rules

| Rule | Level | Auto-fix | Description | |------|-------|----------|-------------| | indent | Warning | ✅ | Enforces 2-space indentation | | quotes | Warning | ✅ | Enforces single quotes | | semi | Error | ✅ | Requires semicolons | | comma-dangle | Warning | ✅ | Requires trailing commas |

Security Rules

| Rule | Level | Auto-fix | Description | |------|-------|----------|-------------| | no-eval | Error | ❌ | Prevents eval() usage | | no-implied-eval | Error | ❌ | Prevents implied eval | | no-new-func | Error | ❌ | Prevents Function constructor |

View complete rule list in global_rules.md

🔧 Customization

Override Rules

You can customize rules by modifying the generated .eslintrc.js:

module.exports = {
  extends: ['windsurf-global-rules'],
  rules: {
    // Override specific rules
    'no-console': 'off',
    'indent': ['error', 4], // Use 4 spaces instead of 2
  }
};

Environment Variables

Set environment-specific behavior:

# Production mode (strict rules)
NODE_ENV=production npm run lint

# Development mode (relaxed rules)
NODE_ENV=development npm run lint

📚 Commands

Package Scripts

# Setup rules in current directory
npm run setup

# Apply rules to current directory
npm run apply-rules

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

CLI Commands

# Setup wizard
npx windsurf-setup

# Apply rules to specific directory
npx windsurf-apply-rules /path/to/project

# Apply rules with options
node index.js apply /path/to/project

# Validate existing setup
node index.js validate /path/to/project

🔍 Validation

Check if rules are properly applied:

npx windsurf-apply-rules --validate

This will check for:

• ✅ ESLint configuration exists
• ✅ Workspace configuration exists
• ✅ Git hooks are configured
• ⚠️ Any missing components

🚨 Troubleshooting

Common Issues

ESLint not found

npm install --save-dev eslint

Git hooks not working

Ensure the hook file is executable:

chmod +x .git/hooks/pre-commit

Rules not applying

Check if .eslintrc.js extends the correct configuration:

module.exports = {
  extends: ['windsurf-global-rules'],
  // ...
};

Debug Mode

Run with debug information:

DEBUG=windsurf-rules npm run setup

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Setup

git clone https://github.com/your-username/windsurf-global-rules.git
cd windsurf-global-rules
npm install
npm run lint

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• NPM Package
• GitHub Repository
• Issue Tracker
• Windsurf IDE

📊 Supported Environments

• Node.js: >= 14.0.0
• ESLint: >= 7.0.0
• Operating Systems: Windows, macOS, Linux
• IDEs: Windsurf, VS Code, WebStorm, Atom

🎉 What's Next?

After installation:

1. Run your first lint check: npm run lint
2. Fix any issues: npm run lint:fix
3. Commit your code: Git hooks will automatically check your code
4. Customize rules: Edit .eslintrc.js as needed
5. Share with team: Commit the configuration files to your repository

Happy coding with Windsurf! 🌊