Usage Examples — Complete Guide

In this tutorial, you will learn about Usage Examples. We cover key concepts, practical examples, and best practices to help you master this topic.

Usage examples show developers how to use your project in real code. Learn to write minimal quickstart examples that produce visible output in 3-5 lines, progressive demos from simple to advanced, and expected output that helps developers verify correct behavior.

What You'll Learn

How to write a minimal quickstart example, how to structure progressive examples that build complexity, how to show expected output for every example, how to demonstrate common use cases, and how to test examples to ensure they work.

Why It Matters

Usage examples are the most valuable part of any README after the description. Developers scan for examples first to understand whether the project solves their problem and how to use it. Great examples convert readers into users.

Real-World Use

The axios README shows a single GET request example in the quickstart. It is minimal, complete, and shows both the request and response handling. Developers see the pattern immediately and adapt it to their needs.

Usage Example Flow

flowchart TD
  A[Usage Section] --> B[Quickstart]
  A --> C[Common Use Cases]
  A --> D[Advanced Examples]
  B --> E[3-5 lines, minimal config]
  C --> F[Real-world scenarios]
  D --> G[Edge cases, integrations]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

The Quickstart Example

The quickstart should be 3-5 lines that do something visible.

// Quickstart: Minimal working example
import { parseFile } from "fastcsv";

const rows = await parseFile("data.csv");
console.log(rows.length); // Number of rows
console.log(rows.columns); // Column names

Progressive Examples

Start simple, then show more realistic use cases.

// Example 1: Simple parsing
import { parseFile } from "fastcsv";

const rows = await parseFile("data.csv");
console.log(rows[0]); // First row

// Expected output:
// { name: 'Alice', age: 30, city: 'New York' }

// Example 2: Parsing with options
import { parseFile } from "fastcsv";

const rows = await parseFile("data.tsv", {
  delimiter: "\t",
  encoding: "latin1",
});

console.log(`Parsed ${rows.length} rows`);
console.log(`Columns: ${rows.columns.join(", ")}`);

// Expected output:
// Parsed 10000 rows
// Columns: name, age, city, email

Showing Expected Output

Every code example should include expected output.

import { parseFile } from "fastcsv";

const rows = await parseFile("users.csv");
console.log(`Total users: ${rows.length}`);
console.log(`First user: ${JSON.stringify(rows[0])}`);
console.log(`Columns: ${rows.columns.join(", ")}`);

// Expected output:
// Total users: 1432
// First user: {"id": "1", "name": "Alice", "email": "alice@example.com"}
// Columns: id, name, email

Common Use Cases

Show examples for the most common things developers want to do.

// Use Case 1: Read a CSV file and process rows
import { parseFile } from "fastcsv";

const users = await parseFile("users.csv");
const adults = users.filter((user) => user.age >= 18);
console.log(`Found ${adults.length} adult users`);

// Use Case 2: Parse a CSV string
import { parseString } from "fastcsv";

const csvString = "name,age\nAlice,30\nBob,25";
const rows = parseString(csvString);
console.log(rows);

// Expected output:
// [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]

Testing Examples

Always test examples against your actual API.

// This example is tested in CI. It uses a real data file from the
// test fixtures. You can run it with: npm run example:quickstart

import { parseFile } from "fastcsv";
import { join } from "path";

const filePath = join(__dirname, "test", "fixtures", "users.csv");
const rows = await parseFile(filePath);
console.log(`Parsed ${rows.length} users`);

// CI validation ensures this example continues to work
// across releases by matching the output against expected values.

Common Mistakes

1. No Usage Section

Projects that show installation but no usage examples leave developers wondering how to use the project.

2. Overly Complex First Example

Showing the most advanced use case first overwhelms beginners. Start with the simplest possible example.

3. No Expected Output

Code examples without expected output leave developers unsure if their code worked correctly.

4. Untested Examples

Examples that have never been run contain typos, missing imports, or reference non-existent APIs.

5. Not Showing Error Cases

Examples that only show success paths. Show what happens when things go wrong.

6. Inconsistent Style

Some examples use CommonJS require, others use ES modules. Pick one style and be consistent.

7. No Realistic Data

Examples with placeholder values like foo, bar, or 123. Use realistic example data.

Practice Questions

1. What makes a good quickstart example?

3-5 lines of code that produce visible output. Includes imports, does something useful, and shows the result. No complex configuration or edge cases.

2. Why show expected output after code examples?

Expected output lets developers verify their code worked. It also demonstrates the data format and types they should expect from the API.

3. How should usage examples be organized?

Quickstart first (minimal), then common use cases (most frequent tasks), then advanced examples (edge cases, integrations, performance).

4. Why test usage examples automatically?

Untested examples contain bugs that break developer trust. Automated testing catches these bugs before they reach the README.

5. Challenge: Write usage examples for a project with a quickstart, two common use cases, and one advanced example. Include expected output for every example.

FAQ

Mini Project: Usage Examples

Write complete usage examples for a fictional library. Include a 3-line quickstart with expected output, two common use cases with realistic data and expected output, and one advanced example. Test every example by running it.

What's Next

Good usage examples show developers how to use the project. Now learn to document the full API with API Reference in READMEs. Then explore Configuration Documentation.