Skip to content
Documentation

Building

Importing a project

Create a new Vorx project from a GitHub repository you already have, and keep the two linked. In beta.

Import is in beta and may not be available in your workspace yet. If you don't see Import under Settings, it isn't switched on for you.

Import creates a new Vorx project from a GitHub repository you already have, and keeps the two linked. It works with apps in Vorx's own project shape, typically an app Vorx built and pushed to GitHub. It does not take any repository on GitHub.

What a repository needs

Import checks the repository before it creates anything. It accepts a Nuxt 4 app in Vorx's project shape, which means the repository has:

  • a package.json that lists Nuxt 4 or later;
  • an app/ folder;
  • a nuxt.config file (.js, .ts, .mjs or .mts);
  • the Vorx preview plugin: vite-plugin-vorx.js at the top level or in tools/, or the @vorx-com/vite-plugin package in package.json.

If anything on that list is missing, Import refuses, names what is missing, and creates no project. It also refuses an empty repository, and one whose top folder holds more than 500 entries.

The reason is practical: Vorx previews and edits an app through that shape. A repository without it would open to a blank preview that Vorx could not change.

Importing a project

  1. Open Settings → Import. Only workspace owners and admins see it.
  2. If no GitHub account is connected yet, choose Connect GitHub and install the Vorx app on the account or organization that owns the repository, giving it access to that repository.
  3. Pick the GitHub account, find the Repository, and choose a Branch. The repository's default branch is selected for you.
  4. Choose Import project. Vorx copies that branch's files into a new project, named after the repository, and opens it.

What comes across, and what does not

Import copies the files on the branch you picked, at its latest commit. That is all it reads. Anything that is not a file in the repository stays where it was: a database and its rows, secrets, a published address or a custom domain. Set those up in the new project.

Import never writes to GitHub. It reads the repository, links it and copies its files, and the repository is unchanged by the import.

After the import, the project stays linked

The new project is linked to the repository and branch you imported, in the same way as a project connected through GitHub sync. From then on, Vorx writes to that repository, and only in these ways:

  • After each successful edit, one commit on the active branch. That starts as the branch you imported. The commit holds the project's files, plus the database schema under supabase/ if the project has a database. It is added on top of the branch's history and never forced over it.
  • A new vorx-sync-… branch when the active branch has commits Vorx has not pulled yet. Your commits stay as they are, and Settings → Git tells you.
  • A new vorx-keep-… branch if you choose to keep the Vorx version when the two have diverged.
  • A branch you create from Settings → Git, started from the active branch.

Vorx does not force-push over the active branch, delete or rewrite a branch, or touch any other branch.

Commits pushed to the active branch on GitHub are meant to come back into the project. That depends on the Vorx deployment receiving events from GitHub. If the project's Settings → Git says changes made on GitHub will not reach Vorx, treat the repository as one-way. GitHub sync explains that notice.

A repository can be linked to only one Vorx project, so a repository that is already linked cannot be imported again.

When Import refuses

Import shows the reason it was given, word for word. The common ones:

  • "… is already linked to another Vorx project": disconnect it from that project in its Settings → Git first. Disconnecting leaves the repository on GitHub untouched.
  • "Vorx's GitHub App cannot see …": on GitHub, give the Vorx app access to that repository, then try again.
  • "This GitHub connection needs to be reconnected": reconnect the GitHub account, then try again.
  • "Can't import …: … this repository is missing …": the repository is not in Vorx's project shape. See What a repository needs.

If something fails after the project was created (the files could not be pulled, for example), the project is kept and marked as failed rather than left looking as if it is still loading. Delete it and try again.

What Import does not do yet

  • It imports only Nuxt 4 apps in Vorx's project shape. A React, Next.js, plain HTML or other app is refused.
  • It imports only from GitHub. GitLab, Bitbucket and uploading a folder are not supported.
  • It links one branch. You can switch the active branch afterwards in the project's Settings → Git.

Next steps