astro-simple-feature-flags
v0.1.0
Published
A simple feature flags integration for Astro. Powered by Content Layer.
Maintainers
sushichan044Readme
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:
1. Install
npx astro add astro-simple-feature-flags2. Add Integration
// astro.config.mjs
import simpleFeatureFlags from 'astro-simple-feature-flags';
import { defineConfig } from 'astro/config';
export default defineConfig({
integrations: [simpleFeatureFlags()],
});3. Create a Feature Flag Configuration
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](https://vite.dev/guide/env-and-mode.html#modes) for detailed information about Vite modes.
viteMode: ['development', 'production'],
});Then run:
npx astro sync4. Define Content Collection via API
[!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(),
};5. Use Flags in Your Astro Components
---
// 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.
📦 Installation & Setup
Requirements
See engines.node and peerDependencies in package.json for supported Node.js and Astro versions.
Step-by-Step Installation
Install the package:
npx astro add astro-simple-feature-flagsCreate 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
🌐 Environment Management
astro-simple-feature-flags supports environment-aware feature flags using Vite modes.
See Vite Modes Docs for more details.
Environment Configuration
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.
});Custom Build Modes
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"
}
}🔷 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 syncafter you changed the value ofconfigFileNamein your integration config.
🤝 Contributing & Resources
Community
- GitHub Repository: sushichan044/astro-simple-feature-flags
- Issues & Bug Reports & Feature Requests: GitHub Issues
Contributing
Contributions are welcome! Feel free to submit PRs. TODO: add CONTRIBUTING.md
- Submit a pull request
Development Setup
# 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 devUseful Resources
- 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/
Changelog
See CHANGELOG.md for version history and release notes.
License
MIT © sushichan044