86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# `lib-*` (라이브러리) Repository README 작성 가이드
|
|
|
|
`lib-*` 접두사를 사용하는 저장소는 다른 애플리케이션에서 가져다 쓸 수 있는 재사용 가능한 코드 패키지(라이브러리)를 관리합니다. 좋은 라이브러리 README는 사용자가 최소한의 노력으로 라이브러리를 설치하고, 핵심 기능을 빠르게 활용할 수 있도록 돕는 '퀵스타트 가이드'와 'API 명세서'의 역할을 동시에 수행해야 합니다.
|
|
|
|
---
|
|
|
|
### 1. 라이브러리 소개 (Library Introduction)
|
|
- **한 줄 요약**: 이 라이브러리가 어떤 문제를 해결하는지, 어떤 기능을 제공하는지 한 문장으로 명확하게 설명합니다.
|
|
- 예시: "React 애플리케이션에서 복잡한 폼(Form) 상태를 쉽게 관리하고 유효성을 검사하는 경량 라이브러리입니다."
|
|
- **주요 특징 (Features)**: 라이브러리의 핵심적인 장점을 3~4가지 항목으로 강조합니다.
|
|
- 예시:
|
|
- 🚀 제로 의존성(Zero-dependency) 및 작은 번들 크기
|
|
- 🎨 손쉬운 커스텀 유효성 검사 규칙 추가
|
|
- 📦 TypeScript 기반의 완벽한 타입 지원
|
|
- hooking 기반의 직관적인 API
|
|
|
|
### 2. 설치 (Installation)
|
|
- **목적**: 사용자가 자신의 프로젝트에 라이브러리를 추가하는 방법을 안내합니다.
|
|
- **패키지 매니저별 명령어**: `npm`, `yarn`, `pnpm` 등 주요 패키지 매니저에 대한 설치 명령어를 모두 제공합니다.
|
|
```bash
|
|
# npm
|
|
npm install @my-org/react-form-validator
|
|
|
|
# yarn
|
|
yarn add @my-org/react-form-validator
|
|
|
|
# pnpm
|
|
pnpm add @my-org/react-form-validator
|
|
```
|
|
- **피어 의존성 (Peer Dependencies)**: 라이브러리가 정상적으로 동작하기 위해 반드시 필요한 다른 패키지(예: `react`, `react-dom`)가 있다면, 명확하게 명시하고 설치를 안내합니다.
|
|
|
|
### 3. 기본 사용법 (Basic Usage / Quick Start)
|
|
- **가장 중요한 섹션**: 라이브러리의 핵심 기능을 보여주는 최소한의 'Hello, World!' 예제 코드를 제공하여 사용자가 즉시 따라 해볼 수 있도록 합니다.
|
|
- **코드 예시**:
|
|
```jsx
|
|
import React from 'react';
|
|
import { useForm, validateEmail } from '@my-org/react-form-validator';
|
|
|
|
function MyForm() {
|
|
const { register, handleSubmit, errors } = useForm();
|
|
|
|
const onSubmit = (data) => {
|
|
console.log('Form data:', data);
|
|
};
|
|
|
|
return (
|
|
<form onSubmit={handleSubmit(onSubmit)}>
|
|
<input
|
|
{...register('email', { required: true, validate: validateEmail })}
|
|
placeholder="이메일"
|
|
/>
|
|
{errors.email && <p>올바른 이메일을 입력해주세요.</p>}
|
|
|
|
<button type="submit">제출</button>
|
|
</form>
|
|
);
|
|
}
|
|
```
|
|
|
|
### 4. API 참고 (API Reference)
|
|
- **목적**: 라이브러리가 제공하는 주요 함수, 컴포넌트, 훅(Hook) 등의 상세한 명세를 제공합니다.
|
|
- **구성**:
|
|
- **`useForm()` Hook**:
|
|
- **`register(name, options)`**:
|
|
- `name` (string, required): 입력 필드의 이름
|
|
- `options` (object): `required`, `minLength`, `validate` 등 유효성 검사 규칙
|
|
- **`handleSubmit(callback)`**:
|
|
- `callback` (function, required): 유효성 검사를 통과했을 때 폼 데이터를 인자로 받아 실행되는 함수
|
|
- **`errors` (object)**: 각 필드의 유효성 검사 실패 정보를 담고 있는 객체
|
|
- **팁**: 내용이 길어질 경우, 별도의 `API.md` 파일로 분리하고 README에서는 해당 파일로 링크를 거는 것이 좋습니다.
|
|
|
|
### 5. 고급 사용법 및 레시피 (Advanced Usage & Recipes)
|
|
- **목적**: 기본적인 사용법을 넘어, 실제 애플리케이션에서 마주할 수 있는 복잡한 시나리오에 대한 해결책을 제공합니다.
|
|
- **예시**:
|
|
- 비동기 유효성 검사 방법
|
|
- 동적 폼 필드 처리하기
|
|
- 외부 UI 라이브러리(예: `Material-UI`, `Ant Design`)와 통합하기
|
|
|
|
### 6. 버전 호환성 (Version Compatibility)
|
|
- **목적**: 라이브러리가 특정 버전의 프레임워크나 환경에서만 동작하는 경우, 이를 명확히 표기하여 사용자의 혼란을 방지합니다.
|
|
- **예시 (표 활용)**:
|
|
|
|
| 라이브러리 버전 | React 버전 호환성 |
|
|
|-----------------|---------------------|
|
|
| `2.x` | `^18.0.0` |
|
|
| `1.x` | `^16.8.0` OR `^17.0.0` | |