How to create your first feature flag for free

Your first feature flag should prove a complete release loop: safe default, internal exposure, production verification, gradual rollout, and cleanup.

A feature flag moves release control out of the deployment itself. You can ship treatment code disabled, turn it on for your own account, expose a small percentage of users, and turn it off without another build.

This tutorial uses GrowthBook because its free Starter plan supports up to 3 users with unlimited feature flags, experiments, and traffic. The example is framework-neutral TypeScript; use the GrowthBook SDK guide for the exact package and initialization in React, Node.js, Python, Java, Go, Flutter, PHP, mobile, or edge runtimes.

Before you start

Choose a safe first feature

Good candidates:

• Show a new dashboard card.
• Change a navigation label.
• Enable a new read-only page.
• Switch between two recommendation layouts.
• Expose a beta search filter.

Avoid:

• Authorization or billing.
• Irreversible writes.
• Schema migrations without compatibility.
• A feature whose old path no longer works.
• A change requiring several services to switch simultaneously.

The first flag is an infrastructure test as much as a product release. Pick something easy to verify and reverse.

Write the flag contract

Record:

The contract prevents a temporary flag from becoming anonymous permanent configuration.

Understand the free plan

The GrowthBook Starter plan currently costs $0, includes 3 users and 1 project, and does not meter core flags, experiments, or traffic. Product packaging can change, so use the live pricing page for current allowances.

Community sources provide useful context: the GrowthBook repository documents the open-source self-hosted path, and the npm package shows JavaScript SDK usage. The official docs remain the implementation source of truth.

Step 1: Create a GrowthBook account

Open the free signup page and create a cloud Starter account. Name the organization and project after the real product rather than this one flag.

GrowthBook creates default environments. Use development while integrating and production only after both states pass testing. Environment separation prevents a local experiment from changing customer behavior.

Do not share a login to remain under the 3-user allowance. Seats are individual platform users; application end users who receive flags do not use seats.

Step 2: Create the feature

In the GrowthBook application:

1. Open Features.
2. Select Add feature.
3. Enter New activity summary as the display name.
4. Use dashboard.release.activity-summary as the key.
5. Choose a Boolean value.
6. Set the default to false.
7. Add the owner, description, and cleanup issue.
8. Save the feature.

The stable key belongs in application code. Do not reuse it later for an unrelated feature; old caches and telemetry would become ambiguous.

Boolean is right for a simple on/off release. GrowthBook also supports strings, numbers, and JSON values for remote configuration or multiple strategies.

Step 3: Install a server SDK

For a TypeScript server, install the current package named by the Node.js SDK documentation. Package names and APIs can evolve, so copy the current quick-start code rather than relying on an old tutorial.

The integration has three responsibilities:

1. Load feature definitions for the correct environment.
2. Provide context attributes such as a stable account ID.
3. Evaluate the flag with a safe fallback.

A simplified wrapper accepts a FeatureFlagClient and a context containing accountId and isEmployee. Its shouldShowActivitySummary method evaluates dashboard.release.activity-summary, maps the account ID to the stable identity and the employee status to a targeting attribute, and returns false if the client cannot produce a value.

The wrapper is intentionally application-owned. It centralizes the key, context mapping, and fallback, making tests and cleanup easier. Replace the illustrative client call with the exact API from your SDK.

GrowthBook SDKs evaluate locally after feature definitions load. Initialization and refresh still use network or cached configuration, so test both.

Step 4: Implement both paths

Keep the conditional at a clear behavioral seam. Evaluate shouldShowActivitySummary once with the request account's ID and employee status. If it returns true, call renderDashboardWithActivitySummary(data); otherwise, call renderClassicDashboard(data).

Avoid checking the flag throughout the rendering tree. One decision per request produces a consistent experience even if configuration changes midway.

Write tests that prove three behaviors:

• A false value renders the classic dashboard.
• A true value renders the activity summary.
• Unavailable configuration uses the classic dashboard fallback.

Also test accessibility, errors, performance, and any downstream calls in both states. A feature flag limits exposure; it does not replace normal QA.

Step 5: Target your account

Add an override rule in the development environment:

• When employee is true, return true.
• Otherwise, use default false.

Preview an employee and nonemployee account. Confirm only the intended context receives treatment.

The GrowthBook DevTools extension can inspect evaluations, override values, and simulate attributes for supported web integrations. The public Chrome Web Store listing describes the debugging workflow.

Do not send sensitive targeting data to a browser. If rules use private account attributes, evaluate on the server.

Step 6: Test failure and transition behavior

Before production:

• Start the application before configuration loads.
• Disconnect the network after load.
• Return an unexpected value.
• Enable and disable while a session is active.
• Run old and new application versions together.
• Verify multiple replicas receive updates.
• Confirm the fallback produces a complete experience.

If the feature writes data, make the old path compatible with treatment writes before relying on rollback. Turning a flag off cannot undo side effects.

The OpenFeature specification provides a vendor-neutral evaluation API model. Even if you use a provider-specific SDK directly, its concepts—typed evaluation, context, hooks, and reasons—are useful for an application wrapper.

Step 7: Deploy treatment code disabled

Merge and deploy with the production default still false. Verify:

• Application health.
• Feature configuration loading.
• The control experience.
• No unexpected treatment exposure.
• Logs and traces include a configuration version or evaluation reason where useful.

Deployment is now separate from release. If the build itself is broken, use ordinary deployment rollback; a flag cannot fix code outside its conditional.

Step 8: Release internally

Add a production rule for an internal account or employee segment. Have someone other than the implementer test:

• Correct account targeting.
• Main task completion.
• Mobile and supported browsers.
• Accessibility.
• Error and latency telemetry.
• Turn-off behavior.

A Reddit story about turning a major UI flag on midday is a reminder that instant configuration can surprise users. Stage visible redesigns and consider session boundaries.

Step 9: Ramp to production

Replace or follow the internal rule with a percentage rollout:

1. 1% for a minimum observation period.
2. 10% after operational checks.
3. 25% or 50% if traffic and risk justify it.
4. 100% after promotion criteria pass.

Define criteria before each change:

• Error rate.
• p95 latency.
• Capacity or cost.
• Customer reports.
• Primary user guardrail.
• Owner and rollback threshold.

The exact percentages are not universal. A low-traffic product may use larger steps; a risky high-volume change may use smaller ones.

GrowthBook Safe Rollouts provide automated guardrail workflows on eligible paid plans. On Starter, use deliberate manual stages and existing observability.

Step 10: Turn the flag into an experiment

If the question is whether the activity summary improves a user outcome—not only whether it works—create an experiment rule:

• Population: Eligible dashboard accounts.
• Randomization unit: Account.
• Control: false.
• Treatment: true.
• Primary metric: Accounts completing a target activity within 7 days.
• Guardrails: Dashboard error and latency.

Use stable account identity and log exposure when the summary can first affect behavior. The GrowthBook experiment analysis connects assignment with metrics from the managed or connected data source.

A gradual rollout checks operational safety. A randomized experiment estimates product impact. One flag can support both workflows, but the questions and decision rules differ.

Step 11: Clean up

After the rollout or experiment:

1. Record the decision.
2. Fix the permanent behavior.
3. Remove the losing branch.
4. Remove the SDK check and wrapper method.
5. Deploy cleanup.
6. Confirm production.
7. Archive or delete the feature configuration.

A practitioner discussion about flag clutter emphasizes removing temporary flags after use. The cleanup issue created at the beginning makes this ordinary planned work.

Keep long-lived kill switches and permission flags only when the continuing control is intentional. They still need owners and tests.

Troubleshooting your first flag

Everyone sees the default

Check the environment key, feature publication state, configuration endpoint, SDK readiness, cache, and context attributes. Inspect evaluation reasons.

Targeting does not match

Compare attribute names, types, null behavior, and case. "true" is not the Boolean true; "123" may not match numeric 123.

Users switch variants

Use a stable identifier. Anonymous cookies, authenticated user IDs, and account IDs have different lifetimes. Choose the unit before release and avoid changing it mid-experiment.

The page flickers

Client-side evaluation may occur after initial render. Prefer server-side or edge assignment for critical initial content, or initialize configuration before rendering with a bounded timeout.

Turning off treatment breaks

The control path may have become incompatible with treatment writes or schemas. Use backward-compatible migrations and test rollback throughout the rollout.

Your next flag should reuse the pattern

The first successful flag establishes more than an if statement. It defines naming, ownership, application wrapping, defaults, test fixtures, environment separation, internal targeting, staged rollout, telemetry, and cleanup.

Keep the pattern small and documented. Add permissions, approvals, automated guardrails, and organization-wide policy only as volume and risk require them.

After the release, save a short implementation note with the flag key, owner, fallback, targeting unit, exposure event, metric, rollout stages, and removal commit. That record gives the next engineer a tested example and prevents conventions from living only in one person's memory. Review the note after the first incident or surprising result; update the template when the real workflow exposes a missing check.

Start with GrowthBook for free, choose one reversible feature, and complete the lifecycle before introducing a second flag. The discipline learned during cleanup is as important as the speed gained during every production release.