@jmlweb/prettier-config-base 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @jmlweb/prettier-config-base
 
+## 1.0.4
+
+### Patch Changes
+
+- 4a9ece1: Update documentation to use pnpm commands instead of npm
+
+## 1.0.3
+
+### Patch Changes
+
+- 6b73301: Add changelog section with link to CHANGELOG.md in package READMEs
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -16,9 +16,11 @@
 ## 📦 Installation
 
 ```bash
-npm install --save-dev @jmlweb/prettier-config-base prettier
+pnpm add -D @jmlweb/prettier-config-base prettier
 ```
 
+> 💡 **Upgrading from a previous version?** See the [Migration Guide](#-migration-guide) for breaking changes and upgrade instructions.
+
 ## 🚀 Quick Start
 
 ### Option 1: Using `package.json` (Recommended)
@@ -86,6 +88,38 @@ function greet(user) {
 }
 ```
 
+## 🤔 Why Use This?
+
+> **Philosophy**: Stop arguing about code style. Let Prettier handle formatting so you can focus on writing code.
+
+This package provides an opinionated Prettier configuration that prioritizes readability and modern JavaScript conventions. The goal is to eliminate formatting debates and establish consistent code style across all projects.
+
+### Design Decisions
+
+**Semicolons (`semi: true`)**: Always use semicolons
+
+- **Why**: Prevents ASI (Automatic Semicolon Insertion) edge cases and ambiguity
+- **Trade-off**: Slightly more verbose, but eliminates an entire class of potential bugs
+- **When to override**: If your team strongly prefers semicolon-free style and understands ASI rules
+
+**Single Quotes (`singleQuote: true`)**: Use single quotes for strings
+
+- **Why**: Consistent with most modern JavaScript codebases and requires less escaping in JSX
+- **Trade-off**: None significant - purely stylistic choice for consistency
+- **When to override**: If working in a codebase that already uses double quotes
+
+**Trailing Commas (`trailingComma: 'all'`)**: Add trailing commas everywhere possible
+
+- **Why**: Cleaner git diffs (changes only affect modified lines) and easier to add items without modifying previous line
+- **Trade-off**: Slightly unusual for developers from other languages, but widely adopted in modern JS
+- **When to override**: If targeting older environments that don't support trailing commas (rare with modern transpilation)
+
+**2 Spaces Indentation (`tabWidth: 2`)**: Use 2 spaces for indentation
+
+- **Why**: Balances readability with horizontal space, standard in JavaScript ecosystem
+- **Trade-off**: May feel cramped compared to 4 spaces, but prevents excessive nesting visibility
+- **When to override**: If your team or organization has standardized on 4 spaces
+
 ## 🎯 When to Use
 
 Use this package when you want:
@@ -129,8 +163,8 @@ Add formatting scripts to your `package.json`:
 Then run:
 
 ```bash
-npm run format        # Format all files
-npm run format:check  # Check formatting without modifying files
+pnpm format        # Format all files
+pnpm format:check  # Check formatting without modifying files
 ```
 
 ## 📋 Requirements
@@ -153,9 +187,125 @@ See real-world usage examples:
 
 ## 🔗 Related Packages
 
+### Internal Packages
+
 - [`@jmlweb/prettier-config-tailwind`](../prettier-config-tailwind) - Adds Tailwind CSS class sorting
 - [`@jmlweb/eslint-config-base`](../eslint-config-base) - ESLint config that works seamlessly with this Prettier config
 
+### External Tools
+
+- [Prettier](https://prettier.io/) - Opinionated code formatter
+- [ESLint](https://eslint.org/) - Pluggable linting utility (use with eslint-config-prettier to avoid conflicts)
+- [Editor Plugins](https://prettier.io/docs/en/editors.html) - Format on save in VS Code, IntelliJ, and more
+
+## ⚠️ Common Issues
+
+> **Note:** This section documents known issues and their solutions. If you encounter a problem not listed here, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+### Conflicts with ESLint
+
+**Symptoms:**
+
+- Code gets formatted by Prettier then changed back by ESLint auto-fix
+- Linting errors about formatting (quotes, semicolons, etc.)
+
+**Cause:**
+
+- ESLint has formatting rules that conflict with Prettier
+- Both tools trying to format the same code
+
+**Solution:**
+
+Install `eslint-config-prettier` to disable conflicting ESLint rules:
+
+```bash
+pnpm add -D eslint-config-prettier
+```
+
+Then add it to your ESLint config (must be last):
+
+```javascript
+// eslint.config.js (flat config)
+import prettier from 'eslint-config-prettier';
+
+export default [
+  // ... other configs
+  prettier, // Must be last!
+];
+```
+
+Or use [`@jmlweb/eslint-config-base`](../eslint-config-base) which already includes this integration.
+
+### IDE Not Formatting on Save
+
+**Symptoms:**
+
+- Files don't format automatically when saving
+- Manual format command works but auto-format doesn't
+
+**Cause:**
+
+- IDE Prettier extension not installed or configured
+- Wrong formatter selected as default
+
+**Solution:**
+
+For VS Code, 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"
+  }
+}
+```
+
+### Configuration Not Being Picked Up
+
+**Symptoms:**
+
+- Prettier uses default settings instead of your config
+- Custom options not applied
+
+**Cause:**
+
+- Configuration file not in the correct location
+- Multiple config files conflicting
+
+**Solution:**
+
+1. Ensure config is in project root (not nested directories)
+2. Use only one configuration method (package.json OR .prettierrc)
+3. Check for conflicting configs in parent directories
+4. Restart your IDE/editor
+
+To verify Prettier finds your config:
+
+```bash
+pnpm exec prettier --find-config-path src/index.ts
+```
+
+## 🔄 Migration Guide
+
+### Upgrading to a New Version
+
+> **Note:** If no breaking changes were introduced in a version, it's safe to upgrade without additional steps.
+
+**No breaking changes have been introduced yet.** This package follows semantic versioning. When breaking changes are introduced, detailed migration instructions will be provided here.
+
+For version history, see the [Changelog](./CHANGELOG.md).
+
+**Need Help?** If you encounter issues during migration, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.
+
 ## 📄 License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlweb/prettier-config-base",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Base Prettier configuration for jmlweb projects",
   "type": "module",
   "main": "./dist/index.cjs",