One-Click Deploys for SolidJS Apps with a README Badge

The fastest way to kill interest in a new library or starter template is to make the first deploy hard. Someone finds your SolidJS component library on GitHub, wants to see it live, and faces a wall of "clone this, install that, configure these five environment variables, run these commands, upload to a host."

A deploy button in the README skips all of that. One click, fill in two fields, wait thirty seconds, get a live URL. PandaStack reads the build config from your repo and auto-detects SolidJS projects built with Vite, so the button works without per-user setup.

Why SolidJS projects need this

Solid apps compile to static bundles via Vite. The build output is a directory of HTML, JS, and CSS that can be served from a CDN with no Node.js runtime. This makes deploys simple, but it also means you lose runtime environment variables — everything must be baked in at build time.

The typical workflow is to document a list of variables in the README, hope users create a .env.local before running npm run build, and cross your fingers that they remember to set production values when deploying. Most people miss this step, deploy an app that tries to hit http://localhost:3001/api, and bounce.

A deploy button with environment prompting fixes this. The user clicks, sees a form asking for the backend URL and any API keys, fills them in, and gets a working app. No .env file, no documentation to skim, no broken demo.

Add the badge to your README

At the top of README.md, below the title and description:

[![Deploy to PandaStack](https://dashboard.pandastack.io/deploy-button.svg)](https://dashboard.pandastack.io/deploy?repo=yourname/solid-starter&env=VITE_API_URL,VITE_SUPABASE_KEY&envDescription=https://github.com/yourname/solid-starter%23environment-variables)

Replace yourname/solid-starter with your repo's owner/name. The env parameter is a comma-separated list of variable names the deploy form should prompt for. The envDescription parameter is a URL (percent-encoded) pointing at setup docs — PandaStack renders it as a help link on the form.

When a user clicks this badge, they land on a pre-filled deploy screen. The repo, branch, and required variables are already set. They authenticate with GitHub (if not already logged in), fill in the environment values, click Deploy, and PandaStack clones the repo, runs the build, and serves the static output from a CDN.

Document the variables in pandastack.json

Query parameters work for simple cases, but they become unreadable when you have five variables with long descriptions. Commit a pandastack.json to the repo root instead:

{
  "type": "static",
  "name": "solid-starter",
  "buildCommand": "npm run build",
  "outputDir": "dist",
  "env": [
    {
      "key": "VITE_API_URL",
      "description": "Backend API base URL (e.g., https://api.yourapp.com)"
    },
    {
      "key": "VITE_SUPABASE_URL",
      "description": "Supabase project URL"
    },
    {
      "key": "VITE_SUPABASE_ANON_KEY",
      "description": "Supabase anonymous public key"
    }
  ]
}

Now the badge in your README can be simpler:

[![Deploy to PandaStack](https://dashboard.pandastack.io/deploy-button.svg)](https://dashboard.pandastack.io/deploy?repo=yourname/solid-starter)

PandaStack reads pandastack.json from the public GitHub contents API, base64-decodes it, and uses its env array to build the form. The key becomes the field label, the description becomes help text below the input. Values merge over query params, so the file always wins.

This is the Vercel-style onboarding flow. Your repo becomes a one-click starter that anyone can fork and deploy without reading setup docs.

How PandaStack detects SolidJS and Vite

When you create a project with "slug": "auto" (or omit the type entirely), PandaStack inspects package.json for framework hints:

• "solid-js" in dependencies → SolidJS project
• "vite" in devDependencies → Vite build tool
• No custom build command → defaults to npm run build
• No output directory specified → checks dist, build, .output/public

For most SolidJS repos created with npx degit solidjs/templates/ts, this works out of the box. The build command is vite build, which the build script in package.json already wraps. The output directory is dist. No configuration needed.

If your project uses a different output directory (like dist/public for a SolidStart static export), set it explicitly in pandastack.json:

{
  "outputDir": "dist/public"
}

Wire environment variables into the build

Vite reads variables prefixed with VITE_ from process.env and replaces them in the source code at build time. In your Solid components, reference them as import.meta.env.VITE_API_URL.

Create a src/config.ts to centralize this:

export const config = {
  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3001',
  supabase: {
    url: import.meta.env.VITE_SUPABASE_URL,
    anonKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
  },
};

When PandaStack runs the build, it sets those environment variables (the ones the user typed into the deploy form), and Vite bakes them into the compiled JS bundle. The deployed app loads config.apiUrl and gets the production URL, not localhost.

Testing the button before you publish it

You do not want to promote a deploy button that breaks halfway through. Test it yourself first.

Push a commit with pandastack.json and the README badge. Open the badge link in a private browser window (to simulate a new user who is not logged in). Authenticate, fill in dummy values for the environment variables, and deploy.

Watch the build logs in the dashboard. Common failures:

• dist directory not found: The build command succeeded but output went somewhere else. Check vite.config.ts → build.outDir.
• Environment variable missing in app: You prompted for VITE_API_URL but the code references import.meta.env.API_URL (missing the prefix). Vite only injects variables that start with VITE_.
• Build command failed with "command not found": The repo uses pnpm but the lockfile is package-lock.json. Commit the correct lockfile or set an install command override.

Once it works, the deploy URL in your test serves a live, working app with the variables you entered.

Add deployment status badges

Deploy buttons are more credible when accompanied by proof that the repo actually builds. Add a build status badge next to the deploy button:

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
[![Deploy to PandaStack](https://dashboard.pandastack.io/deploy-button.svg)](https://dashboard.pandastack.io/deploy?repo=yourname/solid-starter)

Replace the static build badge with a real one from your CI provider if you have automated tests. The combination of "tests pass" and "click to deploy" makes the repo feel production-ready, not just a toy example.

When to use this over CLI or API deploys

Deploy buttons are for public starters, component libraries, and example apps where the goal is to let strangers see a live demo instantly. If you are the only one deploying the repo (internal tool, production app), use the CLI or API instead.

The button workflow assumes:

• The repo is public (PandaStack reads pandastack.json from GitHub without auth).
• The user does not already have a PandaStack account (they will create one during the flow).
• Environment variables are few and simple (API keys, URLs, feature flags, not 20-field configs).

For private repos, team deployments, or complex configs, use panda projects create or script the deploy with the REST API.

Deploy button checklist

Before you add the badge to your README:

1. 1Commit pandastack.json with type, buildCommand, outputDir, and env.
2. 2Test the deploy flow in a private browser window.
3. 3Verify the deployed app loads and uses the environment variables (check network requests in DevTools).
4. 4Document any post-deploy steps (like creating database tables) in the README below the button.
5. 5Link to a live demo URL so users can see the result before deploying their own.

The best starters include three things at the top of the README: a working demo link, a deploy button, and a one-sentence description of what the repo does. Everything else is secondary.

Why this works for SolidJS adoption

Solid is fast and small, but adoption lags React and Vue partly because there are fewer ready-to-run examples. Lowering the deploy barrier helps. A developer searches "SolidJS + Supabase starter," finds your repo, clicks the button, and has a live app in under a minute. They poke around, decide they like it, fork the repo, and start customizing.

Without the button, they clone it, get stuck on environment setup, and move on to the next search result. The easier you make that first experience, the more people stick around.

References

• [SolidJS documentation](https://www.solidjs.com/docs/latest)
• [Vite environment variables guide](https://vitejs.dev/guide/env-and-mode.html)
• [PandaStack deploy button docs](https://docs.pandastack.io)