Understanding STAR goals for effective performance

SMART goals are useful until they aren't.
They produce clear, measurable targets — but they have no mechanism for ownership, no requirement to connect a goal to a larger purpose, and no room for the kind of ambitious thinking that produces breakthrough outcomes. STAR goals were developed, in two distinct forms by two different practitioners, to fill exactly those gaps.
The problem is that the term "STAR goals" gets used inconsistently online, and most explanations conflate frameworks that work very differently and serve different purposes.
This article is for managers, team leads, and individual contributors who set performance goals and want a more effective approach than a checklist. Whether you're running quarterly planning cycles, coaching direct reports, or building your own goal practice, here's what you'll learn:
- What STAR goals actually are — including the two primary frameworks and how they differ from each other and from SMART
- Why self-created goals produce stronger ownership and engagement than top-down assigned ones
- How to connect a goal to a larger purpose so it stays motivating when progress gets hard
- How to build an action plan that turns a well-written goal into concrete, trackable steps
- How to balance realistic targets with stretch goals so your team has both a reliable baseline and an ambitious ceiling
The article moves in that order — from framework clarity, through the psychological and structural principles behind each STAR criterion, to the practical mechanics of execution. By the end, you'll have enough to choose the right framework for your context and apply it without guessing.
STAR goals come in three distinct variants — and conflating them undermines all of them
If you've searched "STAR goals" and walked away more confused than when you started, you're not alone. The term refers to at least two entirely distinct frameworks developed independently by different practitioners for different contexts — plus a third, lesser-known variant that's essentially a SMART clone with different labeling.
Before applying any STAR framework in practice, it's worth understanding exactly what you're working with, where each version came from, and what specific problem each was designed to solve.
The origin and limitations of SMART goals
SMART goals were introduced in 1981 by George T. Doran as a structured approach to writing management objectives. The acronym — Specific, Measurable, Attainable, Relevant, Time-based — gave managers and individuals a reliable checklist for turning vague intentions into concrete targets. For operational planning, SMART remains genuinely useful. It forces specificity, creates accountability through deadlines, and produces goals that can be evaluated objectively.
The problem is what SMART excludes. As personal development practitioner Signe Knutson puts it, "SMART goals are logical, but limited." SMART goals are bounded by current circumstances — they take you from A to B, but only within the range of what already seems achievable. They contain no mechanism for ownership, no requirement that a goal connect to a larger purpose, and no room for aspirational thinking that exceeds what present conditions appear to allow.
For routine operational targets, that's fine. For sustained motivation, meaningful performance, or breakthrough outcomes, those omissions matter.
The education STAR framework: self-created, tied to a greater good, action-oriented, realistic and achievable
The first STAR variant was developed by the Alliance for Catholic Education (ACE) at the University of Notre Dame, specifically for use in blended learning classrooms. The acronym stands for Self-Created, Tied to a Greater Good, Action-Oriented, and Realistic and Achievable.
Each criterion addresses a specific failure mode of conventional goal-setting. The Self-Created criterion reflects a core finding from ACE's work: "Teacher-created learning goals, personalized or otherwise, do not elicit the same sense of ownership as student-created goals." Ownership, in other words, is not a soft benefit — it's a structural requirement for goal commitment.
The Tied to a Greater Good criterion is the most distinctive departure from SMART. It requires that every goal be explicitly connected to a larger purpose — not just a metric to hit, but a reason that metric matters in the context of a longer arc. Action-Oriented means a concrete execution plan must accompany the goal, not just the target itself. Realistic and Achievable mirrors SMART's Attainable criterion, keeping goals grounded in what's genuinely possible given current conditions.
This variant is designed to replace SMART in contexts where ownership and purpose are as important as measurability — particularly anywhere goals are set collaboratively between a guide (teacher, manager) and the person doing the work.
The personal development STAR framework: stretching, tremendous, amazing, rich
The second STAR variant comes from Signe Knutson and represents a more radical departure from SMART thinking. Here, STAR stands for Stretching, Tremendous, Amazing, and Rich. These goals are explicitly not bounded by current reality. They carry no timeline requirement. They are not evaluated against attainability. The entire point is to articulate outcomes that feel impossible under present circumstances — because, as Knutson argues, "when you write it down, it enters the realm of the possible."
Knutson's practical method involves writing six goals daily in a journal: three SMART goals (practical targets across Do, Be, and Have categories) and three STAR goals (aspirational counterparts in the same categories). The STAR goals in this system are designed to invite serendipity — outcomes that conventional planning forecloses because they exceed what current conditions appear to support. This variant doesn't replace SMART; it runs alongside it.
SMART vs. STAR: a direct comparison
The table below captures the structural differences across all three frameworks:
One additional definition worth flagging: a third-party source defines "STAR" as Specific, Time-bound, Achievable, Relevant, Trackable — essentially a SMART variant with "Trackable" substituted for "Measurable." This definition circulates in some corners of the goal-setting literature but doesn't represent either of the primary frameworks covered here, and conflating it with either would muddy the distinctions that make STAR frameworks useful in the first place.
The key takeaway: if you're implementing STAR goals in a performance management or educational context, you're most likely working with the ACE framework. If you're building a personal goal practice designed to coexist with operational targets, Knutson's variant is the relevant model. Both address SMART's motivational limitations — but through fundamentally different mechanisms.
Why self-created STAR goals drive stronger ownership and engagement
There's a familiar pattern in performance management: a manager sets a goal, an employee acknowledges it, and then — despite everyone's good intentions — the goal quietly fades into the background by Q2. The problem isn't ambition or ability. It's design.
When goals are handed down rather than built up, the psychological contract between the person and the objective is compliance, not commitment. The "Self-Created" criterion in the STAR goals framework exists precisely to break that pattern.
The psychology of ownership: why agency changes everything
Ownership, in the context of goal-setting, is not a personality trait that some employees have and others don't. It's a condition that either gets engineered into the process or doesn't. Scott Burgmeyer at becomemoregp.com draws a useful distinction here: ownership is the vested interest in an outcome — the initiative, the sense of responsibility for the process itself — while accountability is accepting responsibility for results after the fact. Both matter, but ownership comes first. Without it, accountability is just blame with better vocabulary.
When someone genuinely owns a goal, the downstream effects are concrete and measurable. Intrinsic motivation replaces the need for external pressure. Because the person accepts that obstacles are theirs to navigate rather than escalate, problem-solving improves. And performance becomes more consistent because the goal isn't something being done to them — it's something they're doing for themselves.
As Kelli Binnings frames it in Brainz Magazine, "ownership gives you the confidence to move beyond intentions and into action" because you've already accepted that you're doing everything within your power to succeed. That proactive orientation also changes how failure lands: when a goal is yours, a setback becomes feedback rather than evidence that the goal was wrong to begin with.
Contrast this with top-down assigned goals, where the psychological contract is fundamentally different. The employee's job is to comply, report, and not fall short of the number. There's no mechanism for the kind of intrinsic investment that sustains effort when things get difficult.
Self-created goals outperform assigned goals — and the data explains why
The data on externally imposed goals — or goals set without genuine individual investment — is not encouraging. Research cited by Brainz Magazine from Ohio State University found that only 9% of Americans who make New Year's resolutions actually keep them, with many abandoning them within the first week.
Resolutions are, by nature, self-chosen, which makes that failure rate striking. The explanation isn't a lack of desire — it's a lack of the structural support that turns intention into execution. If self-chosen resolutions fail at that rate without a supporting framework, assigned goals with even less personal investment face steeper odds.
The workforce context compounds this. The CREW Network has noted that today's employees are no longer satisfied with simply trading time for money. Particularly in the post-COVID era, workers seek meaning, personal growth, and alignment between their work and their values. The original SMART goal model, the CREW Network argues, "fails to bridge the gap between organizational objectives and meaningful engagement that today's employees seek." Self-created goals are one structural response to that gap — not because they're softer or less rigorous, but because they activate a different kind of psychological investment.
Applying self-created goals without losing organizational alignment
The reasonable objection from managers is: if employees write their own goals, how do we maintain alignment to team and company objectives? This tension is real but resolvable, and it dissolves when you stop treating self-created goals as unconstrained goals.
The practical model looks like this: the manager establishes the context — the team's OKRs, the department's strategic priorities, the constraints that are non-negotiable. Within that defined space, the employee drafts their specific goal: what they're committing to, how they'll measure progress, and what success looks like from their vantage point. Manager and employee then review together for alignment. The organizational direction is preserved; the ownership psychology is activated.
The CREW Network describes this shift as moving toward goals that develop "both the person and the professional" — a framing that acknowledges employees aren't just execution units but people whose engagement is a performance variable. Burgmeyer illustrates the cost of skipping this step with a C-suite coaching example: an executive frustrated that her team member "seemed to be looking for directives instead of taking more initiative." That's not a character flaw in the employee. It's the predictable output of a goal-setting process that never gave them genuine agency in the first place.
Ownership is a design outcome. Engineer it into the process deliberately, and the engagement that follows is a structural consequence — not a cultural accident.
Tying performance goals to a greater purpose beyond the metric
There is a well-documented gap between goals that are technically measurable and goals that people actually care about pursuing. Atlassian's research on team goal-setting identifies one of the core reasons teams fall short: a lack of consensus on what success actually means.
That finding points to something deeper than poor metric selection. It suggests that when a goal is only defined by its number, the people responsible for hitting it have no shared story about why the number matters — and without that story, motivation erodes the moment progress stalls.
The "Tied to a Greater Good" criterion in the STAR framework exists precisely to close this gap. It requires that every goal be explicitly connected to something larger than the metric itself — a team outcome, a departmental priority, or an organizational mission. This is not inspirational language for its own sake. It is a structural requirement that forces the goal-setter to answer a question that SMART goals leave optional: why does this target matter beyond the dashboard?
Why metric-only goals fail to sustain motivation
The SMART framework's "Relevant" criterion does ask whether a goal matters. But relevance, as typically applied, is a checkbox — it confirms that a goal is not wildly off-mission without requiring the goal-setter to articulate the specific chain of value from individual action to organizational outcome. A goal like "increase conversion rate by 5% this quarter" passes the relevance test easily. It says nothing about which customers benefit, which product strategy it advances, or what happens to the team if the number moves.
This matters because human motivation under difficulty is not sustained by measurability. It is sustained by perceived significance. When progress stalls — and it will — the question a person asks is not "is this goal specific enough?" It is "is this goal worth the continued effort?" A number without narrative context cannot answer that question. A goal anchored to a clear downstream purpose can.
Self-determination theory offers a useful mechanism here: when a goal connects to something a person genuinely values — not just a metric they've been assigned — the motivation to pursue it becomes internally driven rather than externally pressured. That kind of motivation is associated with greater persistence and higher-quality effort, particularly when progress stalls. The implication for performance management is direct: a goal that explains its own importance is more resilient than one that merely tracks a metric.
The research case for purpose-connected goals
Educational research from the Alliance for Catholic Education supports this argument in a different context with the same underlying logic. Students who understand how a short-term learning target connects to a longer-term outcome demonstrate measurably greater persistence and engagement than students who are given targets without that context.
The psychological mechanism is the same whether the learner is a student or a product manager: when people can trace a near-term goal to a longer-term outcome it serves, abandoning the near-term goal carries a higher psychological cost — because doing so means abandoning the larger outcome as well.
Gallup's longitudinal engagement research reinforces this at the organizational level, consistently finding that employees who report a strong sense of purpose in their work outperform those who do not on retention, productivity, and discretionary effort. Purpose is not a soft benefit — it is a performance variable.
Translating the 'tied to a greater good' criterion into concrete goal language
The practical challenge is translating this principle into goal language that is concrete rather than aspirational. A reliable method works in three levels, moving from the metric outward to the mission.
Start by stating the metric goal in plain terms: what will be measured, by how much, and by when. Then identify the team or department outcome that this metric directly serves — not a vague value like "customer satisfaction," but a specific operational result like "reducing churn in the enterprise segment." Finally, identify the organizational mission or strategic priority that outcome advances.
Once those three levels are clear, write a single connecting sentence: "I will [metric goal] so that [team outcome], which supports [organizational priority]." Applied to an earlier example, this transforms "increase NPS by 10 points" into "increase NPS by 10 points so that the support team can demonstrate retention impact, which supports our strategy of growing revenue through existing accounts rather than new acquisition."
That sentence does not make the goal easier to hit. It makes the goal worth hitting — and that distinction is what the "Tied to a Greater Good" criterion is designed to produce.
Building the action plan: where STAR goals either become real or stay theoretical
A STAR goal without an execution roadmap is, at best, a well-articulated wish. The "Action-Oriented" criterion exists precisely because intention and outcome are not the same thing — and the gap between them is where most goals quietly die.
As Asana puts it plainly: "A goal without a plan is just a wish." The action plan is the operational bridge that answers not just what you're trying to achieve, but how you're going to get there, who is responsible for each step, and by when. For managers and individual contributors alike, this is where goal-setting becomes goal-achieving.
What makes an action plan "STAR-worthy"
Not every to-do list qualifies as an action plan in the STAR sense. A STAR-worthy action plan is a structured document that identifies specific tasks, assigns ownership, sets deadlines, and — critically — connects each step back to the goal's underlying purpose. The Alliance for Catholic Education's framework defines the action plan as the component that provides "the 'HOW' to achieve the goal," and it makes a point that's easy to overlook: the plan should identify responsibilities across multiple stakeholders, not just the person who owns the goal.
Translated into a workplace context, this means a strong action plan doesn't just list what the individual contributor needs to do. It also clarifies what the manager needs to provide (resources, approvals, unblocking), what cross-functional partners need to deliver, and when each dependency is due. This multi-stakeholder framing is what separates a STAR action plan from a personal task list — it makes the goal a shared operational commitment rather than a private aspiration.
Asana's framework for action plans identifies four concrete outcomes a well-built plan delivers: clarity about exactly what steps are needed, accountability through clear ownership and deadlines, efficiency by sequencing tasks in the right order to reduce wasted effort, and motivation by connecting daily work to a larger objective. These aren't soft benefits — they're the structural properties that make a plan executable rather than decorative.
Decomposing a STAR goal into sequenced, time-bound milestones
Once the goal is defined, the practical work is decomposition. A high-level objective like "improve API response time by 30% this quarter" means nothing operationally until it's broken into sequenced, time-bound tasks: audit current performance baselines in week one, identify the top three bottlenecks by week two, implement and test the first optimization by week four, and so on.
The sequencing matters as much as the tasks themselves. Asana's emphasis on "right tasks in the right order" is a useful frame here — dependencies need to be surfaced early so that a missed handoff in week two doesn't collapse the entire plan by week six. Each milestone should specify who owns it and what "done" looks like, not just what needs to happen in the abstract. When milestones are ambiguous, accountability diffuses and slippage becomes invisible until it's too late to course-correct.
The review and adjustment cadence
The most common failure mode in goal management isn't poor goal-setting — it's treating the action plan as a static document reviewed once a year during performance cycles. An action plan is a living artifact. It should be revisited regularly, with a weekly or bi-weekly check-in cadence representing practitioner best practice for goals with meaningful complexity or interdependencies.
Regular review serves two functions. First, it surfaces drift early — tasks that slipped, dependencies that shifted, or assumptions that turned out to be wrong. Second, it creates a forcing function for honest progress assessment rather than optimistic projection. The goal isn't to hold every milestone perfectly on schedule; it's to catch misalignment while there's still time to adjust the plan rather than miss the goal.
Choosing a tracking structure that keeps the action plan a living document
The right tool is the one your team will actually use consistently. Project management platforms like Asana are purpose-built for exactly this use case — linking tasks to goals, assigning owners, setting due dates, and tracking completion over time. For smaller teams or simpler goals, a shared spreadsheet with columns for task, owner, due date, status, and blockers can serve the same function with less overhead.
What matters more than the tool is the structure: every action plan should have a single source of truth that all stakeholders can access and update, a defined review rhythm, and a clear owner responsible for keeping it current. Without that, even the best-designed plan becomes a document rather than a system.
Balancing realism with stretch: the two STAR acronyms are complementary instruments, not contradictions
The two STAR acronyms introduced earlier in this article can appear to contradict each other. One asks whether a goal is "Realistic and Achievable." The other asks whether it is "Stretching, Tremendous, Amazing, and Rich." These are not competing philosophies — they are complementary instruments, and understanding how to use both simultaneously is where goal-setting practice matures from administrative exercise into genuine performance driver.
The case for stretch goals: why ambitious targets produce better outcomes even when missed
Andy Grove, the Intel CEO widely credited as the father of OKRs, described stretch goals as "high-effort, high-risk" targets that are "often assumed to be impossible until a goal becomes possible." That framing is worth sitting with. The stretch goal is not a prediction — it is a deliberate expansion of what a team believes is within reach.
Google, Pinterest, Allbirds, and the National Academy of Engineering all use stretch goals as a formal part of their planning. The National Academy's goal of reverse-engineering the human brain is a useful illustration: no one expects that goal to be completed on a quarterly review cycle. What it does is orient research priorities, attract talent, and generate intermediate breakthroughs that a more conservative framing would never have produced.
The most important calibration tool here is the 70% benchmark. For organizations using OKR-style stretch goals, success is typically defined as achieving roughly 70% of what was set. This is not a consolation prize — it is the design. A stretch goal where 100% achievement feels likely is not stretching enough.
Conversely, when a team hits 70% of an ambitious target, they have frequently outperformed what 100% of a conservative target would have produced. As WhatMatters.com puts it: "even failed goals can result in substantial advancements."
This reframes the skeptic's objection. The concern with stretch goals is usually that they demoralize teams when missed. That concern is valid when stretch goals are set without structure, without milestones, and without a shared understanding that partial achievement is the expected outcome. With those elements in place, the risk profile changes substantially.
Running operational and aspirational goals in parallel
The practical resolution to the realistic-versus-ambitious tension is not to choose between them — it is to run both tracks simultaneously. Operational goals, whether framed as SMART goals or the "Realistic and Achievable" variant of STAR, provide the reliability baseline that teams need to function. Stretch goals layer on top of that foundation, targeting the breakthrough outcomes that operational planning alone will not reach.
Indeed.com describes one clean implementation of this structure: a stretch goal as "an optional extra goal a company can work toward if they exceed their original goal." Their crowdfunding example makes this concrete — an organization raises $10,000 for hurricane relief as its primary goal, then sets a stretch target of an additional $1,500 for food aid. The primary goal is achievable and meaningful on its own. The stretch goal creates upside without undermining the baseline.
This dual-track logic maps directly onto how OKRs distinguish between committed and aspirational objectives. The committed objective is what the team is accountable for delivering. The aspirational objective is what they are aiming toward. Both exist simultaneously, and the presence of the aspirational objective does not dilute accountability for the committed one.
Writing a stretch goal that inspires rather than discourages
The failure mode in stretch goal-setting is not ambition — it is ambiguity. A goal that is large and vague gives a team nowhere to start. The corrective is to pair the ambitious target with defined milestones and explicit thresholds for what partial success looks like.
WhatMatters.com frames this well: the best way to meet a stretch goal is through "defining the milestones to get there" and "communicating specific thresholds for success." The 70% benchmark functions as one such threshold — teams know in advance that hitting 70% of a well-calibrated stretch goal represents strong performance, not shortfall.
There is also a cultural dimension worth naming. Stretch goals only work in environments where partial achievement is treated as progress rather than failure. If a team hits 68% of an ambitious target and is penalized for missing it, the stretch goal framework collapses — not because the goal was wrong, but because the organizational response to near-achievement was wrong. Setting the cultural expectation explicitly, before the goal cycle begins, is as important as setting the goal itself.
Putting STAR goals into practice: which framework fits your context
The frameworks covered in this article are not interchangeable, and applying the wrong one to your context produces goals that miss the motivational mechanisms the framework was designed to activate. The decision is straightforward once you identify what problem you're actually trying to solve.
The ACE framework and Knutson's variant solve different problems — match the tool to the context
Use the ACE framework (Self-Created, Tied to a Greater Good, Action-Oriented, Realistic and Achievable) when:
- You are setting goals collaboratively with a direct report, student, or team member and want to activate genuine ownership rather than compliance
- Your goals need to connect individual performance targets to team or organizational outcomes in a way that sustains motivation through difficulty
- You are replacing a SMART goal process that produces technically correct goals but low engagement
Use Knutson's STAR variant (Stretching, Tremendous, Amazing, Rich) when:
- You are building a personal goal practice and want to run aspirational targets alongside your operational SMART goals
- You want to create deliberate space for outcomes that exceed what current circumstances appear to support
- You are not constrained by organizational alignment requirements and can afford to set goals without timelines or attainability filters
Use standard SMART goals when:
- The goal is purely operational and measurability is the primary requirement
- You need a format that integrates cleanly with existing performance management systems
- The goal-setter already has strong intrinsic motivation and the missing ingredient is structure, not ownership
These three approaches are not mutually exclusive. The most effective goal practices typically run all three simultaneously: SMART goals for operational accountability, ACE-structured STAR goals for collaborative performance development, and Knutson's STAR goals for personal aspiration.
Writing your first STAR goal using the ACE framework's connecting sentence
If you are implementing the ACE framework for the first time, the connecting sentence formula introduced earlier in this article is the fastest path to a well-formed goal: "I will [metric goal] so that [team outcome], which supports [organizational priority]."
Start there. Write the sentence. Then build the action plan around it — identifying the specific tasks, owners, deadlines, and dependencies that turn the commitment into an execution roadmap. Review the plan weekly. Adjust when assumptions prove wrong.
The formula is a starting constraint, not a ceiling. Once the connecting sentence is written, the goal has already satisfied three of the four ACE criteria: it is action-oriented by having a measurable commitment, tied to a greater good by naming the downstream outcome, and realistic by requiring you to state what you're actually committing to. The fourth criterion — self-created — is satisfied by the process of writing it yourself rather than receiving it from above.
Three implementation failures that undermine STAR goals before they start
The most common ways STAR goals fail in practice are not about goal quality — they are about process failures that occur before or after the goal is written.
The first failure is skipping the self-created step. A manager writes the goal, presents it to the employee as a STAR goal, and expects the ownership psychology to activate. It doesn't. The self-created criterion is not a formatting requirement — it is a process requirement. The employee must draft the goal. The manager's role is to establish context and review for alignment, not to write the objective.
The second failure is writing the connecting sentence but never building the action plan. A purpose-connected goal without an execution roadmap is motivating but inert. The "Tied to a Greater Good" criterion sustains motivation; the "Action-Oriented" criterion is what converts that motivation into measurable progress. Both are required. Neither substitutes for the other.
The third failure is treating stretch goals as performance commitments. When a Knutson-style STAR goal — aspirational, timeline-free, explicitly beyond current reach — gets evaluated as if it were a committed OKR, the framework breaks. Stretch goals are instruments for expanding what a team believes is possible. They are not accountability targets. Conflating the two produces the demoralization that stretch goal skeptics correctly warn against.
What to do next
If you manage a team, the highest-leverage first step is to restructure your next goal-setting conversation. Instead of presenting goals for acknowledgment, bring the organizational context — the OKRs, the strategic priorities, the constraints — and ask your direct report to draft their own goal within that space. Review together. The goal that emerges will be more specific, more owned, and more likely to survive the first difficult quarter than anything you could have written for them.
If you are an individual contributor, apply the connecting sentence formula to one current goal this week. Take a goal you already have — a metric you're responsible for — and write the sentence: "I will [metric goal] so that [team outcome], which supports [organizational priority]." If you can't complete the sentence, that's diagnostic information: the goal lacks the purpose connection that will sustain your effort when progress stalls.
If you work on a product team and your goals involve experimentation — conversion rate improvements, feature adoption, retention — GrowthBook's unified platform connects the metrics in your STAR goals directly to the feature flags and experiments driving them, so progress is visible and traceable in the same place you're running tests, rather than inferred from separate dashboards. That kind of direct connection between goal and evidence is exactly what the "Action-Oriented" criterion is designed to produce.
The frameworks in this article are not complicated. What makes them effective is consistent application — writing the goal with the right structure, building the action plan that follows from it, and reviewing both regularly enough to catch drift before it becomes failure.
Related insights
Related Articles
A magazine's home page shows two recent issues. The design team wants subscribers to try a shelf with four. All four covers are public, and changing editions while the page is open should update the shelf immediately. That gives you a small React feature with a useful acceptance test. Click from guest to subscriber and back, and count the covers each time.
We'll put the display limit in a typed local flag, evaluate it inside a React component, and leave the choice of edition with the app. The example runs in a client-rendered React app without a GrowthBook account, an SDK key, or a request for flag rules. For the wider workflow, free feature flags for coding agents explains what to ask an agent to implement and how to review the result.
Define what one flag controls
Start with an existing React and TypeScript app, or create a Vite React project for the example. Install both GrowthBook packages so the definitions and the hooks resolve against compatible SDK versions.
Create src/flags.ts. Here the feature value is a number, which lets the component use the same rendering code for either edition. A future change from four covers to three is one edit to the rule.
A guest falls through to the default of two. A subscriber matches the rule and gets four. This rule applies to every subscriber, so the ID has no effect on the result here. If you later roll the shelf out to a percentage of subscribers, you already have an identity to use for repeatable assignment.
The type registration release note explains the version requirement for LocalFeatures. The registration connects the definition, the attributes, and the value returned by the hook. For the TypeScript mechanics, see Jeremy Dorn's Register pattern walkthrough.
Put the current reader above the shelf
Replace src/App.tsx with the component below. The edition switch is a local fixture so anyone reviewing the change can reproduce both states. In an existing app, take those two values from the active reader in your session layer.
The provider receives an instance initialized with the current reader and the checked-in rules. React can render the correct shelf on the first pass for that reader. If the app is still loading a session, decide what should occupy the shelf in the meantime. For this public list a two-cover guest view is reasonable. On a page where a switch would interrupt the reader, wait for the session before mounting the shelf.
Give your agent the React setup
Use the local flags guide to ask for a typed definition, a provider with the current reader, and a test that changes the edition.
Open the Agent GuideThe useMemo dependencies include the ID and the edition. If a reader subscribes while signed in, their ID can stay the same while their edition changes. Depending only on the ID would leave the old SDK instance in place. Passing a fresh object as the dependency on every render would create unnecessary instances. The example uses the two primitive values the rule setup actually needs.
Read the numeric flag where React renders the list
Create src/IssueShelf.tsx. Keep one stable ID per issue and let the component use the resolved value to select how many items to render.
Keep the hook at the top of the component, inside the provider's subtree. The React SDK supplies the flag value through that provider. Calling a hook inside a click handler or inside the list loop would break the Rules of Hooks. Use the returned number in ordinary render logic.
There are two places you can see the number two in this implementation. The definition's defaultValue is what an ordinary guest gets through evaluation. The 2 passed to the hook is a fallback for a value the SDK can't supply. Giving them the same value makes the basic shelf a sensible fallback, but checking only the guest case would let a broken provider arrangement or missing definition go unnoticed. The subscriber case proves that the component actually received the rule.
The list keys identify magazine issues. Keep those keys independent of the flag. Switching from two covers to four should preserve the identity of the first two rows. There's also no need to remount the whole app with an edition-specific key. React preserves state according to component position and keys. For example, a search input outside the shelf shouldn't lose its text because someone subscribed.
Check the transition in both directions
Use the template's build script to type-check and bundle the app. Once that passes, start the dev server and open the local address it prints.
On first load, the page says guest and lists November and October. Click Switch edition. The same page should say subscriber and add September and August. Click again. The list should return to the original two issues, in order. This last check catches code that appends more results on upgrade and never removes them on downgrade.
For a compile-time check, temporarily replace the numeric fallback with the string "2". Run the build again and inspect the error on the hook call. Then restore 2 and rebuild. If the string compiles, check that src/flags.ts belongs to the same TypeScript project as the component and that the package manager resolved compatible core and React versions.
Look for the core package used by your app and by the wrapper. If the app has several incompatible installations, align the versions before diagnosing the JSX. A team using an existing build script should also confirm it actually runs the TypeScript checker.
Hand off a React change someone can review
Give your coding agent the one-shot local feature flags guide and a short description of the observable behavior. For this shelf, the request can be as specific as the test.
The shelf controls how many public titles to display. If your actual feature unlocks paid articles, enforce access when the server serves an article. A client-rendered flag only decides what to show in that browser. Whenever a change to the display limit can wait for a deployment, the small local file keeps the decision reviewable alongside the component. When an editor needs to change it between issues without an engineering release, that's the point to consider managed rules.
Manage the shelf in GrowthBook
Start a GrowthBook workspace when your magazine team is ready to manage shelf rules between deployments.
Get Started with GrowthBookTwo customers download the same weekly report. One has agreed to preview a new CSV column. The other feeds the old two-column format into an importer. Both requests can land on the same Node.js process, and each needs the right file even if the other request arrives while the report is loading.
This tutorial builds that endpoint with one checked-in feature flag. The process loads the rules once. Each request supplies its own workspace attributes and receives its own evaluation. You can run the whole example on your machine without an account, a client key, or a flag server. The free feature flags for coding agents walkthrough introduces the local approach. Here we'll give the agent a server-specific test to pass.
Set up a small TypeScript service
Use Node.js 22 or newer for this example. In an empty directory, create an npm project that uses ES modules, install the core SDK, and add the TypeScript tools.
Create tsconfig.json at the project root. The sample runs TypeScript directly with tsx and checks types in a separate step. Type checking with tsx explains why the two commands serve different purposes.
The following files all live next to that configuration. The server imports ./flags.js even though the source file is flags.ts. That spelling follows TypeScript's Node.js module resolution for ESM and works with this runner.
Define the report contract in one flag
Create flags.ts. The public format has two columns. The sample preview workspace gets one additional column. The only targeting attribute the rule needs today is reportPreview. Carry the workspace ID too, so two people downloading a report on behalf of the same workspace can share an assignment if you introduce a percentage rollout later.
The SDK type registration update covers this rule syntax and the 2.2.0 minimum. If you misspell reportPreview in a condition or use a string where the boolean flag expects a value, TypeScript can point at the definition. The Register pattern also makes the same feature name available in other modules without threading a generic type through each handler.
Before you add the endpoint, decide what belongs to the process and what belongs to the request. The feature definitions are identical for both customers. Their identity and preview enrollment can differ. If a handler changes an attribute on a single shared user instance before awaiting a database query, another handler could replace that attribute before the first handler resumes.
Give your agent a server-side task
Use the one-shot guide to add checked-in rules. Ask your agent to keep workspace attributes local to each request and demonstrate both CSV formats.
Open the Local Flags GuideCreate a scope when the request arrives
Create server.ts. The Node.js SDK provides GrowthBookClient for the process and createScopedInstance for the current request. The two fixture paths below stand in for two authenticated workspaces. The server binds to the loopback address so you can exercise it locally.
The HTTP handler looks up a workspace, creates its scope, and holds that scope across an asynchronous operation. The short promise-based timer gives a second request time to arrive. In a real export, that's where the database or storage read would happen. Keep the stable client at module scope and the scoped instance inside the handler. If a formatter needs the decision, pass it the boolean or the scoped instance.
In production, resolve the workspace and its access rights from the authenticated session before reading the report. The two selectable paths here are fixtures for public sample data. A caller's choice of a header, query string, or workspace slug can't establish permission to read another customer's report. The endpoint also prevents shared response caching. If you cache real exports, the cache needs to distinguish the workspace and the report format, along with any other inputs that change the response.
Test two requests that overlap
In the first terminal, type-check the service and start it. A successful type check exits quietly. The next command prints the loopback address and keeps the server running.
Save the following as verify.mjs. In a second terminal, run node verify.mjs. Node's built-in fetch calls the local server. Strict assertions compare the full header and data row, including where each row ends.
You should see the single success line. Testing just the preview workspace proves that the code can add a column. Testing both responses catches the more expensive mistake of silently changing an existing customer's export. Keeping the old format assertion around is especially valuable when the downstream importer belongs to someone outside your team.
To check the compile-time boundary, temporarily change gb.isOn("includeUniqueReaders") to gb.isOn("includeUniqueReader") and rerun npx tsc --noEmit. The diagnostic should identify the misspelled key. Restore it before running the server again. A coding agent can include the before-and-after type check and the two CSV headers in its pull request.
Decide when to expand the report
When one preview customer is ready, leave everyone else on the default. If the next step is to enroll a fraction of workspaces, choose an attribute that matches the promise you're making. Hashing a workspace ID lets colleagues downloading the same report share a format. Hashing each user's ID could give two analysts in the same company different column sets. The one-shot guide shows how to express a percentage and hash attribute in a local rule.
A new rule in flags.ts reaches a process through your deployment. During a rolling deploy, the same workspace might hit old and new processes. If customers need a durable choice of export schema, keep supporting the agreed format in the API itself. When the operational requirement is to change targeting between deploys, you can keep the scoped evaluation in the handler and change how the process receives its rules.
Manage report targeting in Cloud
Create a GrowthBook workspace when the team supporting exports needs to expand the preview independently of a server release.
Get Started with GrowthBookYour conference agenda has a new “Show room” button. Reviewers should see it on the first page load. Everyone else should get the existing agenda. If a Server Component renders the old agenda and a browser hook independently decides to show the new button, the first HTML and the browser can disagree.
In the Next.js App Router, the server can make this decision once and pass a boolean to the interactive component. We'll define the flag in the repo, select the preview audience with a local test cookie, and verify the actual HTML for both visitors. Clicking the button will still work after hydration. You can follow along without a GrowthBook account or client key. If you're assigning this work to an agent, the free feature flags for coding agents walkthrough gives the background.
Keep the flag definitions on the server
Use a TypeScript App Router project, or create a small one with create-next-app. These paths assume the project has an app directory at its root. If yours uses src/app, put both app and lib under src so the relative imports still match.
Keep the starter's root layout. Create lib/agenda-flags.ts with the following code. The SDK type registration update explains how LocalFeatures checks the flag and its rule against the registered types. This setup requires version 2.2.0 or later.
The module can reuse the client and rules across requests handled by the same process. It only holds the current visitor's audience inside the function call. Two requests can therefore use the same flag file and get different results. The Node.js SDK documents the scoped client used under the App Router here.
This particular rule has no percentage and needs no visitor ID. The two audiences are sufficient. If the team later asks for a rollout to 10% of attendees, add a stable attendee or registration ID and choose which of those units should stay together. Jeremy Dorn's Register pattern article explains how a change to an attribute type reaches the call sites that construct it.
Read the cookie for this request
Create app/agenda/page.tsx. The static heading can render for everyone. The request-specific content sits behind a Suspense boundary, so the fallback can show a neutral loading message until the server has the cookie.
The App Router's cookies function reads the incoming request asynchronously. Read it inside the visitor-specific component. Keeping that read out of shared cached code lets the surrounding page reuse common content without treating one visitor's decision as another's. This placement also accommodates App Router projects using Cache Components.
Give your agent the Next.js setup
Use the local flags guide with a concrete request to evaluate one flag on the server and return the same decision to the browser.
Open the Local Flags GuideThe cookie in this demo is a convenient way to preview a public UI treatment. Anyone with that cookie can see the room label. To target paying attendees or private sessions, obtain the audience from the verified session on the server and authorize the underlying data separately.
Pass one decision to the interactive component
Create app/agenda/Agenda.tsx. It's a Client Component because a visitor can open and close the room details. Its initial branch comes directly from the boolean supplied by the page.
The client boundary takes a serializable prop. The component receives true or false. The SDK instance, targeting rules, and cookie handling stay in the server module. You don't need a React provider for this component because its only browser-side choice is whether the visitor has clicked the button.
Follow one page load through server rendering and hydration. For a preview visitor, the server can send a section with a “Show room” button. React's first client render gets the same showRoom value and starts with open set to false. Hydration attaches the click handler. Opening the room detail then updates component state and doesn't require another flag evaluation.
Verify the HTML and the click separately
Build the production app and start it on port 3100.
In a second terminal, save this as verify-agenda.mjs in the project root and run node verify-agenda.mjs. The test makes two requests to the same route and looks for a marker on the rendered section. A marker in the HTML helps catch an implementation that only adds the intended layout after JavaScript runs.
Now open http://localhost:3100/agenda in a fresh browser profile. You should see the session title without a room button. In that local page's browser console, set the demo cookie and reload.
Click Show room and look for Room 204. Click Hide room and the room should disappear. This second check proves the component became interactive. If the server response test passes but the click fails, inspect the browser console for a hydration error before changing the flag rules.
Remove the fixture and reload once more. The button should disappear and the agenda title should remain.
The reload is deliberate. Editing the cookie in an already open document doesn't rerun its Server Component. In your app, use the normal session-change flow to request a fresh server render when a visitor signs in, signs out, or leaves a preview group.
Choose where the next flag should be evaluated
For a decision needed in the initial HTML, give the agent an observable requirement. Ask it to show the two HTTP responses, then click the interactive control in the preview. The first check catches an incorrect layout. The second catches correct HTML that never becomes interactive.
If a later feature depends on an action entirely within the browser, evaluate whether its flag belongs in the client tree. The one-shot local flags guide covers both placements. This agenda only needs one server decision. Updating its checked-in rule takes a deployment. Keep that tradeoff in view if the event organizer needs to pause a preview while attendees are already arriving.
Manage the agenda rollout in Cloud
Create a GrowthBook workspace when the organizer needs to adjust a preview audience while your Next.js app is serving attendees.
Get Started with GrowthBookReady to ship faster?
No credit card required. Start with feature flags, experimentation, and product analytics—free.



