Open Source Library README Template

Writing a Great Open Source Library README

A README for an open source library is often the first thing potential users see. It needs to quickly communicate what the library does, how to install it, and how to use it. A well-structured README can mean the difference between adoption and abandonment.

Essential Sections

Badges are critical for open source libraries. At minimum, include:

• npm version badge showing the current published version
• License badge so users know the terms at a glance
• Build status badge proving CI passes on the main branch
• Coverage badge demonstrating test quality

Installation should show both npm and yarn commands:

npm install my-library
# or
yarn add my-library

Usage should start with the simplest possible example, then expand to cover common use cases:

import { parse } from 'my-library';

const result = parse('input string');
console.log(result); // { parsed: true, data: [...] }

API Documentation

For libraries, the Usage section should effectively serve as API documentation. Document each exported function or class with:

• Function signature and parameter types
• Return value description
• A short code example
• Any gotchas or edge cases

TypeScript Support

If your library includes TypeScript definitions, mention it prominently. Users searching for typed libraries will appreciate knowing this upfront. Add a "TypeScript" badge or mention it in the features list.

Contributing Section

Open source libraries benefit greatly from community contributions. Include a Contributing section that explains:

• How to set up the development environment
• How to run tests
• Code style requirements
• The pull request process