Databits Development Standards

Shared development standards, ESLint configs, TypeScript configs, and workflows for consistent code quality across all Databits projects.

Features

• 📚 Comprehensive Documentation - Claude Code instructions, ESLint rules, development workflows
• ⚙️ Shareable Configs - ESLint, TypeScript, and Prettier configurations
• 🔧 Validation Scripts - Automated code quality and architecture checks
• 🚀 Easy Integration - Simple CLI to sync standards across projects
• 📦 Version Control - Semantic versioning for all standard updates

Installation

npm install --save-dev @databits/dev-standards

Quick Start

Initialize in a New Project

# Install the package
npm install --save-dev @databits/dev-standards

# Initialize standards
npx databits-standards init

# Or manually sync
npx databits-standards sync

Add NPM Scripts

Add these to your package.json:

{
  "scripts": {
    "standards:sync": "databits-standards sync",
    "standards:update": "npm update @databits/dev-standards && npm run standards:sync",
    "standards:check": "npm outdated @databits/dev-standards",
    "validate": "./.claude/scripts/validate-code.sh"
  }
}

Usage

Syncing Standards

# Sync everything (docs, scripts)
npx databits-standards sync

# Sync only documentation
npx databits-standards sync --docs-only

# Sync only scripts
npx databits-standards sync --scripts-only

# Force overwrite existing files
npx databits-standards sync --force

Checking for Updates

# Check if updates are available
npx databits-standards update
# Or use npm directly
npm outdated @databits/dev-standards

Updating Standards

# Update package and sync
npm run standards:update

# Or manually
npm update @databits/dev-standards
npx databits-standards sync

Configuration

Extending ESLint Config

Note: This package supports both ESLint 8.x (legacy) and ESLint 9.x (flat config) formats.

ESLint 9.x (Flat Config) - Recommended

For projects using ESLint 9.x, create eslint.config.mjs:

// Basic setup
import baseConfig from '@databits/dev-standards/configs/eslint/base';

export default [
  baseConfig,
  // Your project-specific overrides
];

For TypeScript projects:

import baseConfig from '@databits/dev-standards/configs/eslint/base';
import typescriptConfig from '@databits/dev-standards/configs/eslint/typescript';

export default [
  baseConfig,
  typescriptConfig,
  // Your project-specific overrides
];

For React/Next.js projects:

import baseConfig from '@databits/dev-standards/configs/eslint/base';
import typescriptConfig from '@databits/dev-standards/configs/eslint/typescript';
import reactConfig from '@databits/dev-standards/configs/eslint/react';

export default [
  baseConfig,
  typescriptConfig,
  reactConfig,
  // Your project-specific overrides
];

ESLint 8.x (Legacy Config)

For projects using ESLint 8.x, create .eslintrc.js:

module.exports = {
  // Base JavaScript/TypeScript rules
  extends: ['@databits/dev-standards/configs/eslint/base'],

  // Project-specific overrides
  rules: {
    // Your custom rules here
  },
};

For TypeScript projects:

module.exports = {
  extends: [
    '@databits/dev-standards/configs/eslint/base',
    '@databits/dev-standards/configs/eslint/typescript',
  ],
  // Project-specific overrides
};

For React/Next.js projects:

module.exports = {
  extends: [
    '@databits/dev-standards/configs/eslint/base',
    '@databits/dev-standards/configs/eslint/typescript',
    '@databits/dev-standards/configs/eslint/react',
  ],
  // Project-specific overrides
};

Required Peer Dependencies

Install the necessary peer dependencies based on your config:

# For TypeScript projects
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# For React projects (in addition to above)
npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks

Extending TypeScript Config

Create tsconfig.json in your project:

{
  "extends": "@databits/dev-standards/configs/typescript/tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Using Prettier Config

Create .prettierrc.json in your project:

"@databits/dev-standards/configs/prettier/.prettierrc.json"

Or extend it:

{
  "extends": "@databits/dev-standards/configs/prettier/.prettierrc.json",
  "printWidth": 120
}

What Gets Synced

Documentation (→ .claude/)

• CLAUDE.md - AI agent instructions (synced to project root)
• DEVELOPMENT_GUARDRAILS.md - 4-layer enforcement system
• ESLINT_RULES.md - Complete ESLint rules reference
• CODE_CHECKLIST.md - Step-by-step development workflow
• SUB_AGENT_LINT_FIX_TEMPLATE.md - Template for lint fix sub-agents

Scripts (→ .claude/scripts/)

• validate-code.sh - Code validation script
• architecture-check.js - Architecture rules checker

Configuration Files

• ESLint configs (extended, not copied)
• TypeScript configs (extended, not copied)
• Prettier config (extended, not copied)

Validation

Run validation to ensure code quality:

# Validate entire codebase
./.claude/scripts/validate-code.sh

# Validate specific files
./.claude/scripts/validate-code.sh src/features/**/*.ts

# Auto-fix ESLint issues
./.claude/scripts/validate-code.sh --fix

Development Standards

This package enforces the following standards:

TypeScript

• ❌ ZERO TOLERANCE for any types
• ❌ ZERO TOLERANCE for type assertions (as)
• ✅ Explicit return types on all functions
• ✅ Zod validation for all API responses
• ✅ Type guards from @/lib/type-guards

Code Quality

• Functions < 150 lines
• Cyclomatic complexity < 15
• Nesting depth < 3
• Statements < 35 per function

Formatting

• Single quotes (except to avoid escaping)
• Semicolons required
• Trailing commas in multiline structures
• Strict equality (===)

Security

• No console.log (use logger)
• No hardcoded secrets in comments
• No data leakage patterns

Project-Specific Overrides

You can override any rule in your project's config:

// .eslintrc.js
module.exports = {
  extends: ['@databits/dev-standards/configs/eslint/base'],
  rules: {
    // OVERRIDE: This project needs longer functions for form handling
    // See: docs/architecture/form-architecture.md
    'max-lines-per-function': ['warn', { max: 200 }],
  },
};

Important: Always document why you're overriding a standard.

Version Updates

Semantic Versioning

• Patch (1.2.3 → 1.2.4): Bug fixes, typo corrections
• Minor (1.2.3 → 1.3.0): New rules (non-breaking), new docs
• Major (1.2.3 → 2.0.0): Breaking changes, removed rules

Update Workflow

# 1. Check for updates (weekly/monthly)
npm run standards:check

# 2. Update package
npm run standards:update

# 3. Review changes
git diff .claude/

# 4. Test validation
npm run validate

# 5. Commit
git add .claude/ CLAUDE.md package.json package-lock.json
git commit -m "chore: update dev standards to v1.3.0"

CLI Commands

# Sync standards to current project
databits-standards sync [options]

# Initialize standards in new project
databits-standards init

# Check for updates
databits-standards update

# Show version
databits-standards --version

# Show help
databits-standards --help

Sync Options

• --docs-only - Only sync documentation files
• --scripts-only - Only sync scripts
• --configs-only - Only show config info (configs are extended)
• --force - Overwrite existing files without prompting

Troubleshooting

Package Not Found

# Check registry configuration
npm config get registry

# For GitHub Packages
npm config set @databits:registry https://npm.pkg.github.com

Sync Overwrites Local Changes

# Use specific sync flags
npx databits-standards sync --docs-only

# Or skip force flag (default behavior)
npx databits-standards sync  # Will skip existing files

ESLint Config Not Working

Make sure you have the required dependencies:

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

For React projects:

npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks

Contributing

To update these standards:

1. Make changes in this repository
2. Update version: npm version [patch|minor|major]
3. Publish: npm publish
4. Push tags: git push --follow-tags

Projects will get updates on their next npm update.

License

MIT

Support

• Issues: https://github.com/databits/dev-standards/issues
• Documentation: See /docs directory
• Team: Contact development team lead

Version: 1.0.0 Last Updated: 2025-01-29 Maintained by: Databits Development Team