@dimensional-innovations/tool-config 1.0.0

package/src/tools/prettier/README.md

@@ -0,0 +1,398 @@
+# Prettier Configuration
+
+Framework-aware Prettier configuration with sensible, opinionated defaults.
+
+## Philosophy
+
+This Prettier configuration is designed to:
+
+- **Work out of the box** - Zero configuration needed for all supported frameworks
+- **Be opinionated** - Strong defaults that eliminate bikeshedding
+- **Stay minimal** - Only the essential plugins for each framework
+- **Remain overridable** - All settings can be customized
+
+## Base Configuration
+
+The base preset applies to all frameworks:
+
+```javascript
+{
+  semi: false,                 // No semicolons (cleaner syntax)
+  singleQuote: true,           // Single quotes (except in JSX)
+  trailingComma: 'none',       // No trailing commas (simpler diffs)
+  printWidth: 100,             // 100 character lines (readable but not too long)
+  tabWidth: 2,                 // 2 space indentation (standard)
+  useTabs: false,              // Spaces over tabs
+  arrowParens: 'avoid',        // Avoid unnecessary parentheses in arrow functions
+  bracketSpacing: true,        // Space inside object braces
+  endOfLine: 'lf'             // Unix line endings
+}
+```
+
+## Framework-Specific Behavior
+
+### Vue.js
+
+**Plugin Required**: `prettier-plugin-vue`
+
+**Additional Options**:
+
+- `vueIndentScriptAndStyle: false` - Keep `<script>` and `<style>` aligned with `<template>`
+- `htmlWhitespaceSensitivity: 'ignore'` - Prevent Vue template whitespace issues
+
+**Installation**:
+
+```bash
+npm install --save-dev prettier-plugin-vue
+```
+
+**Example**:
+
+```javascript
+// prettier.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+export default createConfig('prettier')
+```
+
+### React / Solid.js
+
+**No Plugin Required** - Prettier has built-in JSX support
+
+**Additional Options**:
+
+- `jsxSingleQuote: false` - Use double quotes in JSX attributes (React convention)
+- `bracketSameLine: false` - Put closing bracket on new line
+
+**Works with**:
+
+- React 18+
+- Solid.js 1+
+- Any JSX-based framework
+
+### Svelte
+
+**Plugin Required**: `prettier-plugin-svelte`
+
+**Additional Options**:
+
+- `svelteSortOrder: 'options-scripts-markup-styles'` - Standard component block order
+- `svelteStrictMode: false` - Allow flexible syntax
+- `svelteIndentScriptAndStyle: true` - Indent script and style tags
+
+**Installation**:
+
+```bash
+npm install --save-dev prettier-plugin-svelte
+```
+
+**Svelte 5 Support**: Fully compatible with Svelte 5 runes (`$state`, `$derived`, etc.)
+
+### Astro
+
+**Plugin Required**: `prettier-plugin-astro`
+
+**Installation**:
+
+```bash
+npm install --save-dev prettier-plugin-astro
+```
+
+**Automatic Formatting**: The Astro plugin handles all `.astro` file formatting automatically
+
+### Angular / Vanilla JS / Node.js
+
+**No Framework-Specific Configuration** - Uses base preset only
+
+No plugins or special options needed. Works perfectly for:
+
+- Angular 17+
+- Vanilla JavaScript projects
+- Node.js backends
+- TypeScript projects
+
+## Usage
+
+### Basic Setup
+
+```javascript
+// prettier.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('prettier')
+```
+
+### Explicit Framework
+
+```javascript
+// prettier.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('prettier', {
+  framework: 'vue' // 'react' | 'vue' | 'svelte' | 'solid' | 'astro' | 'angular' | 'node' | 'vanilla'
+})
+```
+
+### With Overrides
+
+```javascript
+// prettier.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('prettier', {
+  framework: 'auto',
+  printWidth: 120,
+  semi: true
+})
+```
+
+## Common Overrides
+
+### Use semicolons
+
+```javascript
+export default createConfig('prettier', {
+  semi: true
+})
+```
+
+### Use double quotes everywhere
+
+```javascript
+export default createConfig('prettier', {
+  singleQuote: false
+})
+```
+
+### Enable trailing commas
+
+```javascript
+export default createConfig('prettier', {
+  trailingComma: 'all' // or 'es5'
+})
+```
+
+### Wider print width
+
+```javascript
+export default createConfig('prettier', {
+  printWidth: 120
+})
+```
+
+## NPM Scripts
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run prettier:fix  # Format all files
+npm run prettier      # Check formatting without writing
+```
+
+## VSCode Integration
+
+Install the Prettier extension and add to `.vscode/settings.json`:
+
+```json
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[vue]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[svelte]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}
+```
+
+## Ignoring Files
+
+Create a `.prettierignore` file:
+
+```
+# Build outputs
+dist/
+build/
+.next/
+.nuxt/
+.output/
+
+# Dependencies
+node_modules/
+
+# Generated files
+*.min.js
+*.min.css
+coverage/
+
+# Config files that might have specific formatting
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+```
+
+## Integration with ESLint
+
+This package deliberately **does not** integrate Prettier with ESLint. They remain separate tools:
+
+- **ESLint**: Code quality and correctness
+- **Prettier**: Code formatting
+
+Run them separately:
+
+```bash
+npm run lint && npm run prettier:fix
+```
+
+## Troubleshooting
+
+### Plugin not found error
+
+If you see errors like `Cannot find module 'prettier-plugin-svelte'`:
+
+1. Install the required plugin:
+
+   ```bash
+   npm install --save-dev prettier-plugin-svelte
+   ```
+
+2. Or specify a framework that doesn't need plugins:
+   ```javascript
+   export default createConfig('prettier', { framework: 'react' })
+   ```
+
+### Config not being detected
+
+Make sure your config file is named correctly:
+
+- `prettier.config.js` ✓
+- `prettier.config.mjs` ✓
+- `.prettierrc.js` ✓
+- `.prettierrc.mjs` ✓
+
+And uses ES modules (since your package.json has `"type": "module"`).
+
+### Formatting conflicts
+
+If ESLint and Prettier disagree:
+
+1. **This shouldn't happen** - The ESLint config is designed to work with Prettier
+2. If it does, check your custom ESLint rules
+3. ESLint handles code quality, Prettier handles formatting - they shouldn't overlap
+
+## Design Decisions
+
+### Why no semicolons?
+
+Semicolons are optional in JavaScript due to Automatic Semicolon Insertion (ASI). Omitting them:
+
+- Reduces visual noise
+- Aligns with modern JavaScript trends
+- Works perfectly with proper tooling
+
+If you prefer semicolons, override with `semi: true`.
+
+### Why single quotes?
+
+Single quotes:
+
+- Are more common in modern JavaScript
+- Align with the ESLint configuration
+- Are easier to type (no Shift key needed)
+
+**Exception**: JSX attributes use double quotes (React convention).
+
+### Why no trailing commas?
+
+While trailing commas have benefits (cleaner diffs), we default to `none` because:
+
+- Simpler visual appearance
+- Aligns with base ESLint config
+- Easy to override if you prefer `'all'` or `'es5'`
+
+### Why printWidth 100?
+
+100 characters is a sweet spot:
+
+- Modern monitors can easily display this
+- Allows side-by-side diffs
+- Not so wide that code becomes hard to read
+- Works well with nested structures
+
+## Migration from Other Configs
+
+### From Standard Prettier
+
+If you're migrating from default Prettier settings:
+
+**Main differences**:
+
+- `semi`: `true` → `false`
+- `trailingComma`: `'es5'` → `'none'`
+
+**No changes to**:
+
+- `singleQuote: true` (same)
+- `printWidth: 100` (we use 100, default is 80)
+- `tabWidth: 2` (same)
+
+### From Airbnb
+
+Airbnb typically uses:
+
+- `semi: true` (we use `false`)
+- `singleQuote: true` (same)
+- `trailingComma: 'all'` (we use `'none'`)
+
+Override if needed:
+
+```javascript
+export default createConfig('prettier', {
+  semi: true,
+  trailingComma: 'all'
+})
+```
+
+## Examples
+
+See the `examples/` directory for working examples with all 8 supported frameworks:
+
+- [examples/react-app/](../../../examples/react-app/)
+- [examples/vue-app/](../../../examples/vue-app/)
+- [examples/svelte-app/](../../../examples/svelte-app/)
+- [examples/solid-app/](../../../examples/solid-app/)
+- [examples/astro-app/](../../../examples/astro-app/)
+- [examples/angular-app/](../../../examples/angular-app/)
+- [examples/vanilla-js/](../../../examples/vanilla-js/)
+- [examples/node-backend/](../../../examples/node-backend/)
+
+Each example includes:
+
+- `prettier.config.js` - Configuration file
+- `package.json` - With format scripts
+- Sample code demonstrating formatting
+
+## Resources
+
+- [Prettier Documentation](https://prettier.io/docs/en/)
+- [Prettier Playground](https://prettier.io/playground/)
+- [prettier-plugin-vue](https://github.com/prettier/prettier-plugin-vue)
+- [prettier-plugin-svelte](https://github.com/sveltejs/prettier-plugin-svelte)
+- [prettier-plugin-astro](https://github.com/withastro/prettier-plugin-astro)

package/src/tools/prettier/index.js

@@ -0,0 +1,114 @@
+/**
+ * Prettier configuration factory
+ *
+ * Creates Prettier configurations with framework-aware defaults and auto-detection.
+ */
+
+import { autoDetect } from '../../detectors.js'
+
+import basePreset from './presets/base.js'
+import astroPreset from './presets/frameworks/astro.js'
+import reactPreset from './presets/frameworks/react.js'
+import sveltePreset from './presets/frameworks/svelte.js'
+import vanillaPreset from './presets/frameworks/vanilla.js'
+import vuePreset from './presets/frameworks/vue.js'
+import { prettierIgnoreContent } from './presets/prettierignore.js'
+
+/**
+ * Create a Prettier configuration
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} [options.framework='auto'] - Framework to configure for
+ * @param {string} [options.cwd=process.cwd()] - Working directory for auto-detection
+ * @param {...any} [options.overrides] - User overrides to merge into final config
+ * @returns {Object} Prettier configuration object
+ *
+ * @example
+ * // Auto-detect framework
+ * export default createPrettierConfig();
+ *
+ * @example
+ * // Explicit framework
+ * export default createPrettierConfig({ framework: 'vue' });
+ *
+ * @example
+ * // With overrides
+ * export default createPrettierConfig({
+ *   framework: 'react',
+ *   printWidth: 120,
+ *   semi: true
+ * });
+ */
+export function createPrettierConfig(options = {}) {
+  const { framework: explicitFramework = 'auto', cwd = process.cwd(), ...userOverrides } = options
+
+  // Auto-detect framework if needed
+  const framework = explicitFramework === 'auto' ? autoDetect(cwd).framework : explicitFramework
+
+  // Start with base configuration
+  const config = { ...basePreset }
+
+  // Apply framework-specific preset
+  switch (framework) {
+    case 'vue': {
+      Object.assign(config, vuePreset)
+      console.warn('📝 Prettier: Detected Vue.js - using Vue plugin')
+      break
+    }
+
+    case 'react': {
+      Object.assign(config, reactPreset)
+      console.warn('📝 Prettier: Detected React - using JSX conventions')
+      break
+    }
+
+    case 'solid': {
+      // Solid uses same JSX conventions as React
+      Object.assign(config, reactPreset)
+      console.warn('📝 Prettier: Detected Solid.js - using JSX conventions')
+      break
+    }
+
+    case 'svelte': {
+      Object.assign(config, sveltePreset)
+      console.warn('📝 Prettier: Detected Svelte - using Svelte plugin')
+      break
+    }
+
+    case 'astro': {
+      Object.assign(config, astroPreset)
+      console.warn('📝 Prettier: Detected Astro - using Astro plugin')
+      break
+    }
+
+    case 'angular':
+    case 'node':
+    case 'vanilla': {
+      // These frameworks use base config with no additions
+      Object.assign(config, vanillaPreset)
+      console.warn(`📝 Prettier: Detected ${framework} - using base configuration`)
+      break
+    }
+
+    default: {
+      console.warn(`⚠️  Unknown framework "${framework}", using base configuration`)
+      Object.assign(config, vanillaPreset)
+    }
+  }
+
+  // Apply user overrides
+  Object.assign(config, userOverrides)
+
+  return config
+}
+
+/**
+ * Get the default .prettierignore content
+ * @returns {string} .prettierignore file content
+ */
+export function getPrettierIgnore() {
+  return prettierIgnoreContent
+}
+
+export { prettierIgnoreContent }
+export default createPrettierConfig

package/src/tools/prettier/presets/base.js

@@ -0,0 +1,36 @@
+/**
+ * Base Prettier preset
+ *
+ * Opinionated defaults aligned with CLAUDE.md style guide:
+ * - No semicolons (cleaner syntax)
+ * - Single quotes (consistent with ESLint config)
+ * - No trailing commas (simpler diffs)
+ * - 100 character line width (readable but not too long)
+ * - 2 space indentation (standard)
+ * - LF line endings (Unix standard)
+ *
+ * These settings work universally across all frameworks and can be
+ * overridden by framework-specific presets or user configuration.
+ */
+
+export default {
+  // Code style
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'none',
+
+  // Line formatting
+  printWidth: 100,
+  tabWidth: 2,
+  useTabs: false,
+  proseWrap: 'preserve',
+
+  // Syntax preferences
+  arrowParens: 'avoid',
+  bracketSpacing: true,
+  bracketSameLine: false,
+  singleAttributePerLine: true,
+
+  // Line endings
+  endOfLine: 'lf'
+}

package/src/tools/prettier/presets/frameworks/astro.js

@@ -0,0 +1,15 @@
+/**
+ * Astro-specific Prettier preset
+ *
+ * Configures Prettier for Astro components (.astro files)
+ *
+ * Requires: prettier-plugin-astro (optional peer dependency)
+ */
+
+export default {
+  // Use Astro plugin for .astro files
+  plugins: ['prettier-plugin-astro']
+
+  // Astro plugin handles all formatting automatically
+  // No additional options needed
+}

package/src/tools/prettier/presets/frameworks/react.js

@@ -0,0 +1,15 @@
+/**
+ * React/Solid-specific Prettier preset
+ *
+ * Configures Prettier for JSX files used in React and Solid.js projects
+ *
+ * No plugins required - Prettier has built-in JSX support via babel parser
+ */
+
+export default {
+  // JSX-specific options
+  // Use double quotes in JSX attributes (React convention)
+  jsxSingleQuote: false
+
+  // Note: bracketSameLine is now in base preset
+}

package/src/tools/prettier/presets/frameworks/svelte.js

@@ -0,0 +1,22 @@
+/**
+ * Svelte-specific Prettier preset
+ *
+ * Configures Prettier for Svelte components (.svelte files)
+ *
+ * Requires: prettier-plugin-svelte (optional peer dependency)
+ */
+
+export default {
+  // Use Svelte plugin for .svelte files
+  plugins: ['prettier-plugin-svelte'],
+
+  // Component block ordering: options, scripts, markup, styles
+  // This is the standard Svelte convention
+  svelteSortOrder: 'options-scripts-markup-styles',
+
+  // Don't enforce strict mode (allow flexibility)
+  svelteStrictMode: false,
+
+  // Indent <script> and <style> tags for consistency
+  svelteIndentScriptAndStyle: true
+}

package/src/tools/prettier/presets/frameworks/vanilla.js

@@ -0,0 +1,13 @@
+/**
+ * Vanilla JavaScript/Node.js/Angular Prettier preset
+ *
+ * For frameworks that don't need special Prettier configuration,
+ * this preset is essentially empty and relies on the base preset.
+ *
+ * Used for: Vanilla JS, Node.js backends, Angular projects
+ */
+
+export default {
+  // No framework-specific options needed
+  // Base preset provides everything required
+}

package/src/tools/prettier/presets/frameworks/vue.js

@@ -0,0 +1,20 @@
+/**
+ * Vue-specific Prettier preset
+ *
+ * Configures Prettier for Vue 3 Single File Components (.vue files)
+ *
+ * Requires: prettier-plugin-vue (optional peer dependency)
+ */
+
+export default {
+  // Use Vue plugin for .vue files
+  plugins: ['prettier-plugin-vue'],
+
+  // Don't indent <script> and <style> tags
+  // This keeps them aligned with <template> for consistency
+  vueIndentScriptAndStyle: false,
+
+  // Ignore whitespace sensitivity in HTML
+  // Prevents issues with Vue's template whitespace handling
+  htmlWhitespaceSensitivity: 'ignore'
+}

package/src/tools/prettier/presets/prettierignore.js

@@ -0,0 +1,56 @@
+/**
+ * Default .prettierignore content
+ *
+ * Ignores common build outputs, dependencies, and generated files
+ */
+
+export const prettierIgnoreContent = `# Dependencies
+node_modules/
+.pnp/
+.pnp.js
+
+# Build outputs
+dist/
+build/
+out/
+.next/
+.nuxt/
+.output/
+.vercel/
+.netlify/
+
+# Coverage
+coverage/
+.nyc_output/
+*.lcov
+
+# Lock files
+package-lock.json
+pnpm-lock.json
+yarn.lock
+bun.lockb
+
+# Generated files
+CHANGELOG.md
+
+# Cache directories
+.cache/
+.parcel-cache/
+.turbo/
+.vite/
+
+# Environment files (may contain secrets)
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db
+`
+
+export default prettierIgnoreContent