astro-simple-feature-flags

v2.2.0

Published

a month ago

A simple feature flags integration for Astro. Powered by Content Layer.

0High
0Medium
0Low

sushichan044

withastro astro-integration astro astrojs feature-flags

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.
🎯 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-flags

2. Add Integration

// astro.config.ts
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 for detailed information about Vite modes.
  viteMode: ['development', 'production'],
});

4. 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(),
};

Then run:

npx astro sync

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

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 sync after you changed the value of configFileName in your integration config.

🛠 Dev Toolbar

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.

Flag Console screenshot

Viewing flags

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

Editing flags

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

Limitations

Editable values are limited to JSON primitives: string, number, boolean, and null.
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.

🤝 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 dev

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

astro-simple-feature-flags

✨ Features

🚀 Getting Started

1. Install

2. Add Integration

3. Create a Feature Flag Configuration

4. Define Content Collection via API

5. Use Flags in Your Astro Components

📦 Installation & Setup

Requirements

Step-by-Step Installation

🌐 Environment Management

Environment Configuration

Custom Build Modes

🔷 TypeScript Support

🛠 Dev Toolbar

Viewing flags

Editing flags

Limitations

🤝 Contributing & Resources

Community

Contributing

Development Setup

Useful Resources

Changelog

License