README Templates
Four starting points, depending on what you are describing. Each one is ordinary markdown — copy it into your repository, or open it in the editor here to fill it in and share a rendered link before it ever reaches a README file.
They are deliberately short. A README that answers what it is, how to install it and how to use it beats a long one that buries those three things.
Library or package
For something other developers install and import. Leads with install and usage, because that is what a visitor came for.
# project-name
One sentence on what this does and who it is for.
## Install
```bash
npm install project-name
```
## Usage
```js
import { thing } from 'project-name'
const result = thing({ option: true })
```
## API
### `thing(options)`
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `option` | `boolean` | `false` | What it changes |
| `timeout` | `number` | `5000` | Milliseconds before giving up |
Returns a `Result` object.
## Why not X?
A short, honest comparison with the obvious alternative, including where the
alternative is the better choice.
## Contributing
```bash
git clone https://github.com/you/project-name
npm install
npm test
```
## License
MIT
Command-line tool
For something run in a terminal. Puts a copyable command near the top and documents flags in a table.
# toolname
One sentence on what this does.
```bash
toolname ./src --format json
```
## Install
```bash
# Homebrew
brew install toolname
# npm
npm install -g toolname
```
## Usage
```
toolname [path] [options]
```
| Flag | Default | Description |
| --- | --- | --- |
| `--format` | `text` | Output format: `text`, `json` |
| `--watch` | `false` | Re-run on file changes |
| `--quiet` | `false` | Suppress non-error output |
## Examples
Check a single directory and fail the build on any error:
```bash
toolname ./src --format json || exit 1
```
## Exit codes
| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Errors found |
| `2` | Bad usage |
## License
MIT
Web app or service
For something deployed rather than installed. Covers local setup, environment variables and how to run it.
# App Name
One sentence on what it does. [Live site](https://example.com)
## Stack
| Layer | Technology |
| --- | --- |
| Framework | Next.js |
| Database | PostgreSQL |
| Hosting | Vercel |
## Running locally
```bash
git clone https://github.com/you/app-name
cd app-name
cp .env.example .env.local
npm install
npm run dev
```
Open http://localhost:3000.
## Environment
| Variable | Required | Description |
| --- | --- | --- |
| `DATABASE_URL` | yes | PostgreSQL connection string |
| `SESSION_SECRET` | yes | Random 32-byte string |
## Deploying
```bash
npm run build
npm run start
```
## Architecture notes
Anything a new contributor would otherwise have to work out by reading the
whole codebase — why a decision was made, not just what it was.
## License
MIT
Minimal
For a small project or an internal tool. Everything essential and nothing else.
# project-name
What it does, in one or two sentences.
## Install
```bash
npm install project-name
```
## Usage
```js
import thing from 'project-name'
thing()
```
## License
MIT
Write it here first
Open a template in the editor, fill in the blanks with live preview beside you, and share the link for review before it lands in the repository. No signup.