https://github.com/fontebasso/tiny-feature-flags
A tiny, dependency-free feature flag library designed for serverless, edge, and modern JavaScript runtimes. Built to be safe, deterministic, and easy to integrate anywhere.
https://github.com/fontebasso/tiny-feature-flags
deterministic edge feature-flags rollout sdk typescript
Last synced: 17 days ago
JSON representation
A tiny, dependency-free feature flag library designed for serverless, edge, and modern JavaScript runtimes. Built to be safe, deterministic, and easy to integrate anywhere.
- Host: GitHub
- URL: https://github.com/fontebasso/tiny-feature-flags
- Owner: fontebasso
- License: mit
- Created: 2025-05-03T21:01:56.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2025-05-04T01:10:39.000Z (19 days ago)
- Last Synced: 2025-05-04T01:19:31.404Z (19 days ago)
- Topics: deterministic, edge, feature-flags, rollout, sdk, typescript
- Language: TypeScript
- Homepage:
- Size: 164 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# tiny-feature-flags
[](https://github.com/fontebasso/tiny-feature-flags/actions/workflows/tests.yml)
[](https://www.npmjs.com/package/tiny-feature-flags)
[](https://docs.npmjs.com/generating-provenance-statements)
[](LICENSE)
A tiny, dependency-free feature flag library designed for serverless, edge, and modern JavaScript runtimes. Built to be safe, deterministic, and easy to integrate anywhere.
## Use cases
- Gradual feature rollout using `rollout`
- A/B testing by user traits (plan, region, etc.)
- Environment-based toggles without external services
- Fast evaluation in edge or serverless environments
## Why tiny-feature-flags
- Zero dependencies
- Works in Node.js, Edge Functions, Vercel, Cloudflare Workers
- Runtime evaluation with user traits and percentage rollout
- Designed to be deterministic and side-effect-free
- Fully tested with 100% code coverage
## Installation
```bash
npm install tiny-feature-flags
```
## Quick start
```ts
import { TinyFlags } from 'tiny-feature-flags'
const flags = await TinyFlags.load('https://example.com/flags.json', {
userId: 'user-123',
traits: { region: 'us', plan: 'pro' },
})
if (flags.enabled('newSidebar')) {
showNewSidebar()
}
```
### Sample JSON
```json
{
"newSidebar": { "enabled": true, "rollout": 30 },
"v3Checkout": { "enabled": true }
}
```
## Evaluation logic
Each flag has:
- `enabled: boolean` — the base toggle
- Optional `rollout: number` — deterministic activation based on user ID hash
Unknown flags always return `false`.
## API reference
```ts
class TinyFlags {
constructor(flags: FlagSet, context?: FlagContext)
static async load(url: string, context?: FlagContext): Promise
enabled(flagName: string): boolean
}
```
### Types
```ts
type FlagContext = {
userId?: string
traits?: Record
}
type FlagDefinition = {
enabled: boolean
rollout?: number
}
type FlagSet = Record
```
## Hosting your flags
Serve JSON from any HTTPS endpoint. It can be hosted on:
- GitHub Gist
- Amazon S3
- Your own static server
- CDN with edge caching
## Example: usage with Vercel Edge Function
```ts
export const runtime = 'edge'
import { TinyFlags } from 'tiny-feature-flags'
import { NextRequest } from 'next/server'
export async function GET(req: NextRequest) {
const userId = req.cookies.get('user_id')?.value || 'anonymous'
const flags = await TinyFlags.load('https://example.com/flags.json', {
userId,
traits: { region: 'br', plan: 'pro' },
})
return Response.json({
showNewSidebar: flags.enabled('newSidebar'),
})
}
```
## Tests and reliability
- 100% test coverage using Vitest
- Deterministic logic across all environments
- Includes validation and error handling for unexpected responses
## Design considerations
- Default to `false` for unknown flags
- Stateless by design
- Safe for usage in edge and serverless runtimes
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
This library is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.