---
name: stackblitz-install-auth
description: >-
  Prepare a StackBlitz WebContainer or JavaScript SDK integration with pinned packages, compatible isolation headers, and the correct commercial or private-package authentication path. Use when adding StackBlitz to an existing web application or reviewing its startup contract. Trigger with "install StackBlitz", "set up WebContainers", or "configure WebContainer auth".
argument-hint: "[project-path] [webcontainer|embed]"
allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit
version: 1.7.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
tags:
  - saas
  - stackblitz
  - webcontainers
  - setup
model: inherit
effort: medium
compatibility: Designed for Claude Code
title: stackblitz-install-auth
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/stackblitz-install-auth
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/official-docs.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/stackblitz-install-auth/references/official-docs.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/stackblitz-install-auth`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/stackblitz-install-auth`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/stackblitz-install-auth) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/stackblitz-install-auth`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/stackblitz-install-auth --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/stackblitz-install-auth --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# StackBlitz Integration Preflight

## Overview

This skill produces a repo-grounded installation and startup plan for either a custom WebContainer application or a StackBlitz SDK embed. It separates ordinary browser startup from commercial API-key configuration and organization-scoped private-package authentication.

## Prerequisites

- A named browser application and permission to inspect its package and hosting configuration
- A decision between `@webcontainer/api` and `@stackblitz/sdk`, or evidence that both are needed
- A licensing decision for production commercial use before release

## Tool Discipline

Use `Read`, `Glob`, and `Grep` to inspect package manifests, lockfiles, browser entrypoints, headers, and existing secret bindings. Use `WebFetch` only for current official StackBlitz or WebContainers documentation. Use `Write` or `Edit` only after the evidence pass, and never place API keys or OAuth material in source files.

## Current Contract

- Pin the package version selected by the repository's dependency policy; do not install an unreviewed moving tag.
- Call `configureAPIKey` before `WebContainer.boot()` when a commercial license supplies an API key.
- Call `auth.init` before boot when organization users need private-package access; the user must be logged in, belong to the issuing organization, and authorize the site.
- Match the `Cross-Origin-Embedder-Policy` response header to the `coep` boot option. Use HTTPS outside localhost.
- A StackBlitz SDK embed is a separate surface and does not require booting a custom WebContainer in the host application.

## Authentication

Public prototypes may not need user authentication, but production commercial use requires a licensing review. Treat the WebContainer API key as a secret runtime binding. Treat the auth client ID and scope as configuration, initialize auth during page loading, and handle `need-auth`, `authorized`, and `auth-failed` explicitly. Never infer that ordinary StackBlitz login grants access to private packages.

## Workflow

1. Inspect the framework, package manager, lockfile, client/server boundary, CSP, and current response-header configuration.
2. Choose the minimum package surface and record the installed or proposed pinned version.
3. Decide whether the integration needs a commercial API key, organization auth, neither, or both.
4. Configure consistent COOP/COEP headers and the matching boot option; verify the final HTML response, including cached responses.
5. Add one startup module that orders API-key configuration, auth initialization, and the single boot call correctly.
6. Validate in a supported desktop browser over the same origin and headers intended for deployment.

## Approval Boundaries

Default to inspection and a proposed patch. Require explicit authorization before changing production headers, CSP, identity-provider settings, licensed API-key bindings, or deployment configuration. Never create, rotate, expose, or revoke a credential without a separately authorized operational step.

## Output

Return the selected integration mode, package/version evidence, licensing and auth decision, header/boot contract, changed or proposed files, verification results, rollout plan, rollback, and unresolved browser or policy risks.

## Error Handling

| Condition | Response |
|---|---|
| API key configured after boot | Stop and move configuration before the first boot call. |
| Auth reports `need-auth` | Present the user-authorized flow; do not loop or fabricate authorization. |
| `crossOriginIsolated` is false | Inspect actual response headers and cache behavior before changing code. |
| Integration mode is unclear | Compare custom runtime requirements with embed-only requirements before installing both SDKs. |

## Examples

Given an existing Vite app, identify its lockfile and hosting headers, select a pinned WebContainer API version, document whether commercial licensing applies, and propose a single ordered startup module without reading any secret value.

## Resources

- [Official StackBlitz and WebContainers references](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/stackblitz-install-auth/references/official-docs.md)
- [WebContainer API reference](https://webcontainers.io/api)
- [StackBlitz JavaScript SDK](https://developer.stackblitz.com/platform/api/javascript-sdk)
