@larrym/file-saver

A modern, lightweight file-saver library with full ESM support for downloading files in the browser.

Features

- ✨ Full ESM (ES Modules) support
- 📦 CommonJS compatible
- 🔷 TypeScript support with full type definitions
- 🌐 Browser-based file downloads
- 🎯 Multiple file format support (Text, JSON, CSV, Blob)
- 📥 URL-based file downloads
- 🔒 Zero dependencies
- 🪶 Lightweight

Installation

``bash
npm install @larrym/file-saver
`

Usage

$3

`typescript
import { saveAs, saveText, saveJSON, saveCSV, downloadURL } from '@larrym/file-saver';

// Save a blob
const blob = new Blob(['Hello, World!'], { type: 'text/plain' });
saveAs(blob, 'hello.txt');

// Save text
saveText('Hello, World!', 'hello.txt');

// Save JSON
const data = { name: 'John', age: 30 };
saveJSON(data, 'data.json', true); // true = pretty print

// Save CSV
const csvData = [
['Name', 'Age'],
['John', '30'],
['Jane', '25']
];
saveCSV(csvData, 'data.csv');

// Download from URL
await downloadURL('https://example.com/file.pdf', 'document.pdf');
`

$3

`javascript
const { saveAs, saveText, saveJSON } = require('@larrym/file-saver');

saveText('Hello, World!', 'hello.txt');
`

$3

`typescript
import fileSaver from '@larrym/file-saver';

fileSaver.saveText('Hello, World!', 'hello.txt');
`

API Reference

$3

Save any data as a file.

- data: Blob | string | ArrayBuffer - The data to save
- fileName: string - The name of the file
- options: SaveOptions (optional)
- autoBom: boolean - Automatically add BOM for text files (default: true)

`typescript
const blob = new Blob(['data'], { type: 'text/plain' });
saveAs(blob, 'file.txt');
`

$3

Save text content as a file.

- text: string - The text content
- fileName: string - The name of the file

`typescript
saveText('Hello, World!', 'hello.txt');
`

$3

Save JSON data as a file.

- data: unknown - The data to save as JSON
- fileName: string - The name of the file
- pretty: boolean - Format with indentation (default: true)

`typescript
const data = { message: 'Hello' };
saveJSON(data, 'data.json', true);
`

$3

Save CSV data as a file.

- csvData: string | string[][] - CSV string or array of arrays
- fileName: string - The name of the file

`typescript
const data = [
['Name', 'Email'],
['John', 'john@example.com']
];
saveCSV(data, 'contacts.csv');
`

$3

Download a file from a URL.

- url: string - The URL to download from
- fileName: string - The name to save the file as
- Returns: Promise

`typescript
await downloadURL('https://example.com/image.jpg', 'photo.jpg');
`

Browser Compatibility

This library works in all modern browsers that support:
- Blob API
- URL.createObjectURL
- HTML5 download attribute

TypeScript

Full TypeScript support is included with type definitions.

`typescript
import { saveAs, SaveOptions } from '@larrym/file-saver';

const options: SaveOptions = {
autoBom: true
};

const blob = new Blob(['data']);
saveAs(blob, 'file.txt', options);
`

Publishing

This package uses npm's trusted publishing feature with OIDC authentication for secure, token-free publishing from GitHub Actions.

$3

1. Create or login to your npm account at https://www.npmjs.com

2. Navigate to package settings:
- Go to your package page (or create a new scoped package placeholder)
- Click on "Settings" tab
- Scroll to "Publishing access" section

3. Add trusted publisher:
- Click "Add trusted publisher"
- Select "GitHub Actions"
- Fill in the details:
- Organization/Username: larrymotalavigne
- Repository: file-saver
- Workflow filename: publish.yml
- Environment name: npm-publish

4. Save the configuration

$3

1. Create a new release on GitHub:
`bash
git tag v1.0.0
git push origin v1.0.0
`

2. Go to GitHub → Releases → Create a new release

3. The GitHub Action will automatically publish to npm using OIDC authentication

$3

You can also trigger the workflow manually from the Actions tab in GitHub.

$3

- Node.js >= 18.0.0
- npm >= 11.5.1 (for OIDC trusted publishing)

Development

`bash


Install dependencies

npm install

Build the package

npm run build

The build outputs to dist/ folder with:

- dist/index.js (ESM)

- dist/index.cjs (CommonJS)

- dist/index.d.ts (TypeScript types for ESM)

- dist/index.d.cts (TypeScript types for CommonJS)

``

License

MIT © Larry Motalavigne

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

This package uses npm's trusted publishing with OIDC, which provides:
- No long-lived tokens to manage or leak
- Cryptographic verification of publisher identity
- Automatic provenance attestations
- Enhanced supply chain security

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.