Hf Static Space Deployer

HF Static Space Deployer

Deploy static web content to Hugging Face Spaces in a repeatable way.

Choose the correct deployment mode

Use this skill when the app is static output.

1. Plain static files (no build step)

• index.html + CSS/JS files committed directly.
• Use sdk: static and app_file: index.html.

1. Build-first static app

• Framework source (React/Vite/Svelte/Vue/etc.) requires build.
• Use sdk: static, app_build_command, and app_file pointing to built HTML (for example dist/index.html).

1. Do not use this skill when server-side runtime is required

• If the app needs a backend process, custom server routes, or non-static runtime behavior, use Docker Spaces instead.

Minimum required repo structure

At minimum, ensure:

• README.md with YAML metadata block (includes sdk: static).
• App entry HTML referenced by app_file.
• Any source/build files needed for build (if using app_build_command).

See templates in:

• [references/readmetemplates.md](references/readmetemplates.md)

Standard workflow

1. Authenticate with Hugging Face.
2. Create Space as repo_type=space and space_sdk=static.
3. Upload project files.
4. Wait for build/startup.
5. Validate app URL and behavior.

Use exact commands from:

• [references/deployworkflows.md](references/deployworkflows.md)

Deployment quality checks

After upload/build, verify:

1. Space build succeeds.
2. app_file exists at expected path.
3. Site loads at the Space URL.
4. Asset paths resolve correctly (no broken CSS/JS).
5. If SPA:

• hash routing works directly; history routing may need fallback strategy.

1. If query/hash syncing with parent page is required, use Spaces postMessage pattern.

See:

• [references/troubleshooting.md](references/troubleshooting.md)

Security and platform caveats

1. Static Spaces run inside an iframe on huggingface.co/spaces/....
2. For static Spaces, variables/secrets are available to browser JS through window.huggingface.variables.
3. Do not treat static frontend variables as confidential server-only secrets.
4. Cookie behavior can differ from first-party hosting due to iframe constraints.

Use:

• [references/securityandplatformnotes.md](references/securityandplatformnotes.md)

CI/CD guidance

Prefer one of:

1. Push directly with hf upload.
2. Mirror from GitHub with a GitHub Action that pushes to the Space repo.

Use templates from:

• [references/deployworkflows.md](references/deployworkflows.md)

Local tooling bundled with this skill

• scripts/scaffold_static_space.py: generate a README.md metadata block and optional GitHub Action workflow.
• scripts/validate_static_space.py: validate local projects and/or existing deployed Spaces (for example --space-id evalstate/foo).

Output expectations

When helping a user, always produce:

1. Final README.md YAML block.
2. Exact deploy command sequence.
3. Suggested CI option (manual or GitHub Actions).
4. Post-deploy validation checklist.
5. Troubleshooting steps tailored to framework/output path.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fast-agent-ai
• Source: fast-agent-ai/skills
• License: MIT

Install and usage instructions live in the source repository linked above.