A simple, type-safe feature flag integration for Astro, powered by the Content Layer API.
- 🌍 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.
- 🎯 Simple API - Query any flag with a single function call.
Get up and running in under 5 minutes:
npx astro add astro-simple-feature-flags// astro.config.ts
import simpleFeatureFlags from 'astro-simple-feature-flags';
import { defineConfig } from 'astro/config';
export default defineConfig({
integrations: [simpleFeatureFlags()],
});Write your flags definition.
// 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'],
});Warning
If you already defined a collection named astro-simple-feature-flags, this integration will not work.
// src/content.config.ts
import { defineFeatureFlagCollection } from "astro-simple-feature-flags/content-layer";
export const collections = {
// Your existing collections...
...defineFeatureFlagCollection(),
};Then run:
npx astro sync---
// 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');
---
<html>
<body>
{isFooEnabled && (
<div class="new-feature">
🎉 New feature is live!
</div>
)}
{barEnabledRate > 0 && (
<p>Bar enabled rate: {Math.round(barEnabledRate * 100)}% of users</p>
)}
</body>
</html>That's it! Your feature flags are now working with full type safety and environment awareness.
See engines.node and peerDependencies in package.json for supported Node.js and Astro versions.
-
Install the package:
npx astro add astro-simple-feature-flags
-
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/flagsto the configFileName option in your integration settings.
- By default, the configuration file is named
astro-simple-feature-flags supports environment-aware feature flags using Vite modes.
See Vite Modes Docs for more details.
The viteMode array in your configuration maps Vite's build modes to your defined environments:
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.
});Set custom Vite modes for different deployment targets:
// package.json
{
"scripts": {
"dev": "astro dev",
"build": "astro build",
"build:staging": "astro build --mode staging",
"build:testing": "astro build --mode testing",
"preview": "astro preview"
}
}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.
The integration ships a Flag Console in the Astro Dev Toolbar, giving you a live view and interactive editor for all feature flags during development.
Open the toolbar and click the flag icon to open the Flag Console. It displays every flag key, its current value, its type, and the active Vite mode (e.g. development).
Primitive flag values (boolean, number, string, null) are editable inline and the changes are written directly to flags.config.*:
- Boolean flags render as a toggle switch.
- Number and string flags render as a text input.
Click Update to apply, or Reset to revert. A successful save triggers HMR so the updated values are applied immediately.
Note
Successful toolbar saves write back the validated input object, not the schema output. This means transform() schemas remain type-safe in flags.config.*.
- Editable values are limited to JSON primitives:
string,number,boolean, andnull. - Only static
defineConfig({ flag: { … } })object literals are supported. Flags defined via variables, spread operators, computed expressions, arrays, or nested objects are shown as read-only.
- GitHub Repository: sushichan044/astro-simple-feature-flags
- Issues & Bug Reports & Feature Requests: GitHub Issues
Contributions are welcome! Feel free to submit PRs. TODO: add CONTRIBUTING.md
- Submit a pull request
# Clone the repo
git clone https://github.com/sushichan044/astro-simple-feature-flags.git
cd astro-simple-feature-flags
# Install dependencies
pnpm install
# Build the package
pnpm --filter astro-simple-feature-flags build
# Test in playground
pnpm --filter @repo/playgrounds-simple-flag dev- Astro Documentation: https://docs.astro.build
- Astro Integration API: https://docs.astro.build/en/reference/integrations-reference/
- Astro Content Loader API: https://docs.astro.build/en/reference/content-loader-reference/
See CHANGELOG.md for version history and release notes.
MIT © sushichan044
Built with ❤️ for the Astro community