How to Create and Submit a New StackBlitz Example

A StackBlitz example is a small, runnable lesson. You will clone the examples repository, scaffold one project per framework, document it, port it, check it, and open a pull request.

The process has more steps than a typical change, but each step is simple, and this guide walks through all of them.

Pick a Reference Example

Every new example should follow a proven pattern. The replace-example already exists in Angular, React, Vue, and Svelte, so it is a good reference. Open its Angular project, read how the service owns the state, and notice how the component only displays the result and forwards user actions.

Choose one clear concept for your example. One behavior is easier to explain, easier to review, and easier to compare across frameworks.

Key takeaway: Angular is the canonical version. The other frameworks are ports of it, so build Angular first.

Clone the Repository

Clone the repository and create a branch for your example. Run these commands in the directory where you keep your projects:

git clone https://github.com/sdux-vault/stackblitz-examples.git
cd stackblitz-examples
git checkout -b add-my-first-example

If you have already forked the repository, clone your fork instead and open a pull request from your branch to dev when you are ready.

Install the Dependencies

Install the repository tools once from the root. These packages power the scaffold, the port, and the checks you will run later.

npm install

Scaffold the Angular Project

Use the package scripts to create the project. Start with Angular, since it is the canonical version:

npm run scaffold:angular

The script asks for a name. Enter my-first. It lowercases the name, converts spaces to hyphens, and adds -example, so the project is created at stackblitz/angular/my-first-example. It also refuses to overwrite an existing example, so choose a name that is not already taken.

The scaffold copies shared global files into every example. Do not edit those global files for one example. Put your example's code inside its own folder.

Write the Example Code

The scaffold gives you three files to change:

• example.service.ts owns the state.
• example.component.ts forwards user actions.
• example.component.html displays the result.

Keep the same split in your example. Only the service talks to the Vault. The component reads the state and calls service methods.

Start with the service. It declares the state shape, registers the FeatureCell, initializes the pipeline, and exposes the methods the component can call. This is the replace example's service, trimmed to its essentials:

import { Injectable } from '@angular/core';
import { FeatureCell, injectVault } from '@sdux-vault/angular';

export interface Example {
  id: number;
  name: string;
  lastName: string;
}

@FeatureCell('example-feature-cell-key')
@Injectable({ providedIn: 'root' })
export class ExampleService {
  readonly #vault = injectVault<Example[]>(ExampleService);
  readonly state = this.#vault.state;

  constructor() {
    this.#vault.initialize();
  }

  replace(input: Example[]): void {
    this.#vault.replaceState({ loading: false, value: input, error: null });
  }

  reset(): void {
    this.#vault.reset();
  }
}

Next, the component. It reads the state from the service and forwards each button click to a service method. It never changes the state itself:

import { Component, inject } from '@angular/core';
import { ExampleService } from './example.service';

export class ExampleComponent {
  readonly #exampleService = inject(ExampleService);
  readonly state = this.#exampleService.state;
  readonly sample = [
    { id: 11, name: 'Luke', lastName: 'Skywalker' },
    { id: 38, name: 'Leia', lastName: 'Organa' },
    { id: 9, name: 'Han', lastName: 'Solo' }
  ];

  loadSample(): void {
    this.#exampleService.replace(this.sample);
  }

  resetState(): void {
    this.#exampleService.reset();
  }
}

Last, the template. It has two buttons and shows the state once the pipeline has a value:

<button (click)="loadSample()">Load Sample State</button>
<button (click)="resetState()">Reset State</button>
@if (state.hasValue()) {
  <pre>{{ state.value() | json }}</pre>
}

Follow the flow when you click a button: the template calls the component, the component calls the service, the service updates the Vault, and the pipeline sends the new value back to the template.

Build your example by changing the sample data, the state shape, and the service methods to teach your behavior. The code is enough to run for now. You will add the documentation in a later step, so keep the comments short until then.

Run It Locally

Each example is a standalone project. Install its dependencies and start its development server from its own folder:

cd stackblitz/angular/my-first-example
npm install
npm start

Open the address the terminal prints. For Angular, it is http://localhost:4200. Click every control, confirm the output changes the way the lesson describes, and fix anything that looks wrong before you continue.

Add the Documentation

Documentation is generated with an AI prompt, so you do not have to write every comment by hand. The repository provides the same instructions for two tools:

• GitHub Copilot: open .github/prompts/add-stack-docs.prompt.md and run it against your Angular project.
• Codex: use the skill at .agents/skills/add-stack-docs/SKILL.md against the same project.

Point the prompt at stackblitz/angular/my-first-example. It adds clear JSDoc for classes, methods, fields, parameters, and return values. Read the result and make sure it explains what each symbol does in the lesson. Do not let the prompt describe internal mechanics. Keep the explanations at the API boundary.

Port to the Other Frameworks

Once Angular works and is documented, create the React, Vue, and Svelte versions with the port prompt. There are two versions of it, one for each tool:

• GitHub Copilot: use .github/prompts/port-example.prompt.md.
• Codex: use .agents/skills/port-example/SKILL.md.

In Copilot, run the port for each framework:

@port my-first-example --to=react
@port my-first-example --to=vue
@port my-first-example --to=svelte

In Codex, ask the agent to use the port skill for the same Angular project and the same target framework. Use one run per framework so each change is easy to review.

The port keeps the same pipeline, UI, class names, and documentation. Only the framework syntax and the reactive wrapper change. Review the generated files against Angular before you run them. The Angular project should not change during a port.

Verify Each Framework

Run every framework you created. Use the same steps as Angular, once for each folder:

cd stackblitz/react/my-first-example
npm install
npm start
cd ../../vue/my-first-example
npm install
npm start
cd ../../svelte/my-first-example
npm install
npm start

Each version should behave the same way. Compare the output side by side with Angular.

Then run the repository checks from the root:

npm run lint
npm run format:check
npm run typecheck
npm run docs:coverage

All four checks must pass before you open a pull request. The npm run verify command runs the main checks together, and CI runs them again on every pull request.

Verify on StackBlitz

Push your branch, then open each framework folder in StackBlitz. The URL pattern is the same for every example:

https://stackblitz.com/github/sdux-vault/stackblitz-examples/tree/main/stackblitz/angular/my-first-example

Replace angular with react, vue, or svelte to check the other frameworks. Open the preview and confirm it works as it did locally. The example must run without any changes on your machine.

Commit and Open a Pull Request

Commit your work on the branch, push it, and open a pull request:

git add stackblitz/
git commit -m "Add my-first example for Angular, React, Vue, and Svelte"
git push -u origin add-my-first-example
gh pr create --fill

The repository's pull request template asks for a description, the related issue, the frameworks you changed, and your local and StackBlitz results. Fill in each section. A reviewer should be able to open one folder, run it, and understand the lesson from the UI and the documentation.

Deeper Dive

Read the StackBlitz examples repository for the scaffold templates, the existing examples, and the pull request checklist. You can also open the StackBlitz Examples page to compare your example with the others.