github-raw-fetcher

A tiny TypeScript/JavaScript utility for fetching raw file contents from GitHub repositories.
Supports both plain text and JSON files.

✨ Features

• Fetch raw files from any public GitHub repo
• Configure username, repository, and branch once and reuse
• Override options per-request if needed
• Built-in helper for parsing JSON safely
• Written in TypeScript with full type support

📦 Installation

npm:

npm install github-content-fetcher

Yarn:

yarn add github-content-fetcher

🚀 Usage

ESM Example

import GithubContentFetcher from 'github-content-fetcher';

const fetcher = new GithubContentFetcher('octocat', 'Hello-World', 'main');

// Fetch raw text file
const readme = await fetcher.getRawContent('README.md');
console.log(readme);

// Fetch and parse JSON
type Config = { version: string; features: string[] };
const config = await fetcher.getJSONContent<Config>("config.json");
console.log(config.version);

CJS Example

const GithubContentFetcher = require('github-content-fetcher').default;

const fetcher = new GithubContentFetcher('octocat', 'Hello-World', 'main');

(async () => {
    const readme = await fetcher.getRawContent('README.md');
    console.log(readme);

    const config = await fetcher.getJSONContent();
    console.log(config);
})();

📚 API

constructor(username: string, repository: string, branch?: string)

Create a fetcher bound to a GitHub repo.

• username – GitHub username or org
• repository – repository name
• branch (optional, defaults to main) – branch to fetch from

getRawContent(fileName: string, options?: ContentGetterOptions): Promise<string>

Fetch the raw text of a file.

Params:

• fileName – path to the file inside the repo
• options (optional) – { username?, repository?, branch? } overrides

getJSONContent<T = unknown>(fileName: string, options?: ContentGetterOptions): Promise<T>

Fetch a JSON file and parse it.

Params:

• fileName – path to the file inside the repo
• options (optional) – same as above

Type Parameter:

• T – expected JSON shape (default: unknown)

⚠️ Limitations

• Works with public repos. For private repos, you’ll need to extend it with GitHub API + token authentication.
• Uses fetch – available in browsers and Node.js v18+. For older Node versions, you may need a polyfill (like node-fetch).

📝 License

MIT © 2025 sebastian-goat