@quicksand-cloud/prettier-config/README.md

QuickSand Cloud Prettier 配置 - 企业级代码格式化配置，支持多种文件类型和智能导入排序

# @quicksand-cloud/prettier-config

QuickSand Cloud 的 Prettier 配置包，提供统一的代码格式化规范。

## 📦 安装

```bash
npm install --save-dev @quicksand-cloud/prettier-config
```

## 🚀 使用方法

### 基本使用

在项目根目录创建 `prettier.config.js` 文件：

```javascript
import config from '@quicksand-cloud/prettier-config';

export default config;
```

或者使用 CommonJS：

```javascript
const config = require('@quicksand-cloud/prettier-config');

module.exports = config;
```

### 在 package.json 中配置

```json
{
  "prettier": "@quicksand-cloud/prettier-config"
}
```

## ⚙️ 配置详情

### 基础格式化规则

- **行宽**: 80 字符
- **缩进**: 2 个空格
- **制表符**: 使用空格而非制表符
- **分号**: 语句末尾添加分号
- **引号**: 使用单引号（JSX 中使用双引号）
- **尾随逗号**: 在所有可能的地方添加尾随逗号
- **括号间距**: 对象字面量的括号内添加空格
- **行尾**: 使用 LF (Unix) 换行符

### 特殊规则

- **箭头函数**: 单参数时也添加括号
- **JSX 括号**: 多行 JSX 元素的 `>` 符号不单独成行
- **HTML 空白敏感性**: 遵循 CSS 显示属性
- **Vue 文件**: 不缩进 `<script>` 和 `<style>` 标签

### 启用的插件

此配置包含以下 Prettier 插件：

- **@prettier/plugin-oxc**: 基于 Oxc 的高性能解析器
- **prettier-plugin-packagejson**: 格式化 package.json 文件
- **@ianvs/prettier-plugin-sort-imports**: 自动排序导入语句
- **prettier-plugin-jsdoc**: 格式化 JSDoc 注释
- **prettier-plugin-sh**: 格式化 Shell 脚本

## 🎯 支持的文件类型

- **JavaScript**: `.js`, `.cjs`, `.mjs`
- **TypeScript**: `.ts`, `.cts`, `.mts`
- **React**: `.jsx`, `.tsx`
- **Vue**: `.vue`
- **JSON**: `.json`
- **Markdown**: `.md`, `.mdx`
- **HTML**: `.html`
- **CSS**: `.css`, `.scss`, `.less`
- **YAML**: `.yml`, `.yaml`
- **Shell**: `.sh`, `.bash`

## 🛠 与其他工具集成

### 与 VS Code 集成

1. 安装 Prettier 扩展：

```bash
code --install-extension esbenp.prettier-vscode
```

2. 在 VS Code 设置中配置：

```json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.configPath": "./prettier.config.js"
}
```

### 与 lint-staged 集成

配合 `@quicksand-cloud/lint-staged-config` 使用：

```javascript
import lintStagedConfig from '@quicksand-cloud/lint-staged-config';

export default lintStagedConfig;
```

### 命令行使用

在 `package.json` 中添加脚本：

```json
{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}
```

## 🚀 导入排序功能

此配置启用了自动导入排序功能，导入语句将按以下顺序排列：

1. **Node.js 内置模块**: `fs`, `path`, `http` 等
2. **第三方库**: `react`, `lodash`, `axios` 等
3. **内部模块**: 相对路径导入
4. **类型导入**: TypeScript 类型导入（如果使用）

示例：

```javascript
import fs from 'fs';
import path from 'path';

import React from 'react';
import { Button } from 'antd';

import { utils } from '../utils';
import { config } from './config';

import type { User } from '../types';
```

## 🔧 自定义配置

如果需要自定义规则，可以扩展基础配置：

```javascript
import baseConfig from '@quicksand-cloud/prettier-config';

export default {
  ...baseConfig,
  printWidth: 120,
  singleQuote: false,
};
```

## 📋 依赖要求

- `prettier` >= 3.6.0

## ⚠️ 注意事项

- 建议在整个团队中使用相同的配置以保持代码风格一致
- 部分插件可能会影响格式化性能，但提供了更好的代码组织
- 与 ESLint/Oxlint 配合使用时，建议禁用样式相关的 lint 规则

## 🔄 与其他配置包的关系

本配置包是 QuickSand Cloud Specs 配置集合的一部分，建议与以下包配合使用：

- [@quicksand-cloud/oxlint-config](https://www.npmjs.com/package/@quicksand-cloud/oxlint-config) - 代码质量检查
- [@quicksand-cloud/lint-staged-config](https://www.npmjs.com/package/@quicksand-cloud/lint-staged-config) - Git 提交前处理
- [@quicksand-cloud/commitlint-config](https://www.npmjs.com/package/@quicksand-cloud/commitlint-config) - 提交信息规范
- [@quicksand-cloud/typescript-config](https://www.npmjs.com/package/@quicksand-cloud/typescript-config) - TypeScript 配置
- [@quicksand-cloud/specs](https://www.npmjs.com/package/@quicksand-cloud/specs) - 配置管理工具

## 📄 许可证

MIT

## 🔗 相关链接

- [Prettier 官方文档](https://prettier.io/)
- [Prettier 插件开发指南](https://prettier.io/docs/en/plugins.html)