ZIP and GitHub import

Import a Project

Project import turns local or repository-backed work into a Vibecodr workspace only after the uploaded bytes are verified and normalized.

User-facing import guide for staged ZIP and GitHub project workflows.

Implementation focus

Use this before uploading a ZIP, importing from GitHub, or diagnosing an import/build job that did not produce a runnable preview.

Expected outcomes

Upload is not verification

A project import starts with bytes, but Vibecodr cannot treat uploaded bytes as a safe project until they are verified. ZIP and GitHub imports move through a staged upload and import flow so size, file shape, entry points, package manager, and build recipe can be checked before cost-bearing work continues.

This distinction matters for users because a completed browser upload does not mean the project is ready to build or publish. The import result should tell you whether Vibecodr found a browser-ready static app, a supported build recipe, or a shape that needs changes before it can run.

  • Use ZIP import for local projects and GitHub import for repository-backed work.
  • Keep `.env`, tokens, private credentials, and unrelated large files out of the archive.
  • Expect a staged upload to become verified before import/build work proceeds.
  • If verification fails, fix the archive shape instead of retrying the same bytes.

Prepare the project shape

A good import has a clear browser entry point or a supported build output. Static projects should include browser-ready files such as `index.html`. Build-backed projects should include package metadata, a supported package manager, and a build command that writes to the expected output directory.

`vibecodr.json` can provide safe hints for project intent, but it does not override platform checks. If the archive says one thing and the package/build facts say another, Vibecodr prefers the facts it can verify.

  • Use `npm` or `pnpm` for build-backed imports.
  • Avoid `yarn` and `bun` for Vibecodr build jobs unless the product explicitly adds support later.
  • Use `build.recipe`, `build.installCommand`, `build.buildCommand`, and `build.outputDir` in `vibecodr.json` only when detection needs a safe hint.
  • Let lockfiles and `package.json` package-manager facts choose `npm` or `pnpm`; do not rely on `vibecodr.json` to override the install tool.
  • Make sure the build output exists after the build command finishes.
  • Keep backend source separate from browser runtime output so trusted code does not leak into the vibe.

Recover from import failures

Most import failures are recoverable project-shape problems: an oversized ZIP, too many files, unsupported package manager, missing entry file, missing build script, or output directory mismatch. The fastest recovery is to fix the project and import again with a smaller, clearer archive.

If the import job returns an error, keep the route or job id, the source type, the package manager, the expected recipe, and the visible error message. Do not include private tokens, raw `.env` values, or credential-bearing URLs in support reports.

  • For static projects, confirm `index.html` and assets are inside the ZIP root or expected folder.
  • For Vite, Astro, Next static export, or SvelteKit static projects, confirm the build output directory.
  • For Pulse-backed projects, confirm server files are source files, not bundled into public client output.

Example and read next

Example: you zipped a local Vite project and the upload finished. Wait for staged upload verification, confirm the recipe and output directory, then fix project shape if import reports a missing build result.

Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system.

Related documentation

  • /docs/supported-build-recipes
  • /docs/studio
  • /docs/troubleshooting
  • /docs/source