Deploy a folder or archive

Not everything lives in a Git repository. Sometimes the code is a folder on your laptop, a download, or an archive someone sent you. Synq can take that folder or archive, work out what is inside, build it, and give you back a running app. No Git remote needed.

Three ways in

The desktop app shows the same panel, so its Folder tab uploads the folder the same way.

Upload a folder from the browser

A browser cannot read your disk on its own, so you tell Synq what you are deploying, then hand it the folder. It is packed in your browser and uploaded.

What gets uploaded

Only your source. These are left out, because the build recreates them:

• anywhere in the tree: .git, node_modules, vendor, .next, .nuxt, .svelte-kit, .astro, .output, .vite, .turbo, .cache, .nx, .react-router, .dev-secrets.json;
• at the top of the folder only: dist, build and data (the same names deeper down, such as src/data, are kept).

If everything was skipped you see "That folder looks empty (or everything was ignored). Pick a project folder." Choose the folder that holds your package.json (or go.mod, Cargo.toml, requirements.txt, and so on).

Upload an archive

The Archive tab takes a single archive file of your app and treats its contents like an uploaded folder.

How the archive is unpacked

• The format is recognized from the file's contents, not only its name.
• Every tar flavor gets the same checks and limits as a .tar.gz: .tar.bz2 and .tar.xz are unpacked with the server's bzip2 and xz programs (included in the Synq API image), and .tar.zst with the runtime's built-in zstd. If a native install lacks one of those programs, that format is refused with a message naming the missing program; the other formats keep working.
• If everything in the archive sits in one top-level folder (the usual result of zipping a folder, or of GitHub's "Download ZIP"), that folder becomes the app's root. Otherwise the archive's root is used.
• The macOS __MACOSX folder is removed, and a stray top-level .DS_Store doesn't stop a single wrapping folder from being used as the app root.
• Unlike a folder upload, nothing else is skipped: remove node_modules and build output before archiving to keep the upload small.
• Symbolic links are allowed only when they point inside the archive. "Files that would land outside the archive, and links that leave it, are rejected."

Archive limits

Errors you may see: "Choose a .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz or .tar.zst file.", "7z and rar are not supported; repack as .zip or .tar.gz.", "This archive is larger than 300 MB.", "Source archive contains too many entries", "Source archive exceeds its size limit", "Encrypted zip archives are not supported", and "Source archive is empty".

CLI

The CLI does the whole thing in one command. Run synq deploy --folder inside the folder to upload it. It packages the folder, uploads it, detects the stack, creates the project (or reuses the linked one), and deploys it, the same pipeline as the browser upload.

# From inside your project folder:
synq deploy --folder --name my-app --watch

• --name is only a fallback name. The detected name wins: the name field in package.json when the folder has one, otherwise a name Synq generates for the upload. To choose the project, use synq init or --project <id> (below).
• --watch follows the build logs in your terminal until it finishes. Leave it off and Synq prints a command to follow the logs later.
• --server <id> picks the server (see synq server list).

Deploy to the same project again

Point the CLI at the project explicitly, or a repeat deploy can create a new project. A folder whose package.json has a name reuses the project with that name, but a folder without one gets a new generated name on every run.

Link the folder once with synq init, or pass --project <id> on each run:

synq init             # pick a project to link this folder to
synq deploy --folder  # uploads this folder to the linked project
synq deploy --folder --project <project-id>  # or target a project without linking

synq init writes a small .synq/project.json file so later commands know which project this folder belongs to. It links to a project that already exists, so create one first (with a folder deploy, or in the panel).

After the first deploy

• Redeploy rebuilds the files you uploaded last time. To ship changed files, upload again (the CLI in a folder linked with synq init is the quickest), or connect a repository under Source & Triggers → Source (Link a Repository) so pushes can deploy.
• There is no push webhook for uploaded code. To trigger redeploys from outside, use a deploy hook.

Troubleshooting

Related guides