astro-simple-feature-flags


> A simple, type-safe feature flag integration for Astro, powered by the Content Layer API.

✨ Features

- 🌍 Environment-aware - Use different flag values for each Vite mode.
- 🔒 Type-safe - Full TypeScript support with auto-generated types.
- 🔄 Hot-reload - Flag changes trigger HMR in the dev server.
- 📦 Content Layer Powered - Built on Astro 5's Content Layer API.
- Works in both SSG and SSR modes.
- 🎯 Simple API - Query any flag with a single function call.

🚀 Getting Started

Get up and running in under 5 minutes:

$3

``bash
npx astro add astro-simple-feature-flags
`

$3

`js
// astro.config.mjs
import simpleFeatureFlags from 'astro-simple-feature-flags';
import { defineConfig } from 'astro/config';

export default defineConfig({
integrations: [simpleFeatureFlags()],
});
`

$3

Write your flags definition.

`ts
// flags.config.ts
import { defineConfig } from 'astro-simple-feature-flags/config';
import { z } from 'astro/zod';

export default defineConfig({
schema: z.object({
isFooEnabled: z.boolean().optional().default(false),
barEnabledRate: z.number().min(0).max(1).optional().default(0),
}),
flag: {
development: {
isFooEnabled: true,
barEnabledRate: 1.0,
},
production: {
barEnabledRate: 0.1,
},
},
// Define the Vite modes for your environments.
// You can add more modes as needed (e.g., 'staging', 'testing').
//
// See https://vite.dev/guide/env-and-mode.html#modes for detailed information about Vite modes.
viteMode: ['development', 'production'],
});
`

Then run:

`bash
npx astro sync
`

$3

> [!WARNING]
> If you already defined a collection named astro-simple-feature-flags, this integration will not work.

`ts
// src/content/config.ts
import { defineFeatureFlagCollection } from "astro-simple-feature-flags/content-layer";

export const collections = {
// Your existing collections...
...defineFeatureFlagCollection(),
};
`

$3

`astro
---
// src/pages/index.astro
import { queryFeatureFlag } from 'virtual:astro-simple-feature-flags';

// Query feature flags! Params and return types are fully typed.
const isFooEnabled = await queryFeatureFlag('isFooEnabled');
const barEnabledRate = await queryFeatureFlag('barEnabledRate');
---



{isFooEnabled && (


See engines.node and peerDependencies in package.json for supported Node.js and Astro versions.

$3

1. Install the package:

`bash
npx astro add astro-simple-feature-flags
`

2. Create your flags configuration file:

- By default, the configuration file is named flags.config.{ts,js,mjs,cjs,cts,mts}.
- To use a different path, for example .config/flags.config.ts, pass .config/flags to the configFileName option in your integration settings.

🌐 Environment Management

astro-simple-feature-flags supports environment-aware feature flags using Vite modes.

See Vite Modes Docs for more details.

$3

The viteMode array in your configuration maps Vite's build modes to your defined environments:

`ts
export default defineConfig({
// Your environments
flag: {
development: { / dev flags / },
staging: { / staging flags / },
production: { / prod flags / },
testing: { / test flags / },
},

// Map Vite modes to environments
viteMode: ['development', 'staging', 'production', 'testing'],

// When Vite runs in 'development' mode, it uses the 'development' flags.
// When Vite runs in 'staging' mode, it uses the 'staging' flags.
// And so on.
});
`

$3

Set custom Vite modes for different deployment targets:

`json
// package.json
{
"scripts": {
"dev": "astro dev",
"build": "astro build",
"build:staging": "astro build --mode staging",
"build:testing": "astro build --mode testing",
"preview": "astro preview"
}
}
`

🔷 TypeScript Support

Params and return types for queryFeatureFlag are fully typed automatically.

See .astro/integrations/astro-simple-feature-flags/flags.d.ts for the generated types in your Astro project.

> [!WARNING]
> You must run astro sync after you changed the value of configFileName in your integration config.

🤝 Contributing & Resources

$3

- GitHub Repository: sushichan044/astro-simple-feature-flags
- Issues & Bug Reports & Feature Requests: GitHub Issues

$3

Contributions are welcome! Feel free to submit PRs. TODO: add CONTRIBUTING.md

1. Submit a pull request

$3

`bash


Clone the repo

$3

- Astro Documentation:
- Astro Integration API:
- Astro Content Loader API:

$3

See CHANGELOG.md for version history and release notes.

---

License

MIT © sushichan044

---