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.mjs
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.
- 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