CodeSpaces Migration

migration.md

Migration Guide: CodeSandbox Repositories to GitHub Codespaces

1. Vocabulary Mapping

CodeSandbox Term	GitHub Codespaces Term	Difference
Sandbox	Codespace	A Sandbox is the branch. A Codespace is an instance of a branch.
Forking a Sandbox	Creating a Branch	In Codespaces, you create a git branch first, then launch a container for it.
VM Snapshot	Prebuilds	CodeSandbox saves memory state; Codespaces "pre-installs" dependencies so you start fast.
.codesandbox/tasks.json	devcontainer.json (Scripts)	CodeSandbox uses a dedicated tasks file; Codespaces uses postCreateCommand or postStartCommand.

---

2. Transitioning the "Instant" Workflow

The CodeSandbox Experience (What you're used to)

In CodeSandbox Repositories, you visit a branch and the VM is already running with your tasks (like npm start) pre-executed. If you want to make changes, you "Fork," which clones the running VM state into a new branch/URL instantly.

The GitHub Codespaces Experience (The new way)

• The Web Experience: Navigate to your repo on GitHub and create a Branch. Click "Create Codespace on [branch]".
• The Desktop Experience: Open VS Code locally. Use the GitHub Codespaces extension to create or connect to environments directly.
• Warm Start via Prebuilds: To replicate the "instant" feel where you don't wait for npm install, you must enable Prebuilds in your GitHub Repo Settings. This tells GitHub to run your setup scripts every time code is pushed, so the container is "warm" when you join.

---

3. Step-by-Step: Starting a Feature

Step A: Branching

In CodeSandbox, you "Forked" to branch. In the new workflow:

1. Go to the GitHub repository.
2. Create a new branch (e.g., feat/new-ui).
3. Click Code → Codespaces → +.

Step B: Moving Tasks to .devcontainer.json

Since you no longer have a .codesandbox/tasks.json, you move those commands into the devcontainer.json lifecycle hooks:

• Instead of setupTasks: Use "postCreateCommand": "npm install".
• Instead of runTasks: Use "postStartCommand": "npm start".

Step C: Connecting from VS Code Desktop

The Codespaces extension is built-in and native:

1. Open local VS Code.
2. Click the Remote Explorer (bottom-left green icon or sidebar).
3. Select GitHub Codespaces.
4. Your new environment will be listed there. Click to connect.

---

4. Key Developer Differences

• Persistence: In CodeSandbox, every change is "live." In Codespaces, while your work is saved in the cloud VM, you still need to Commit and Push for others to see it in the repo.
• Secrets: Move your sandbox env variables to GitHub Codespaces Secrets (Settings → Secrets → Codespaces).
• Multiplayer: CodeSandbox is "live" by default. For Codespaces, use the Live Share extension within your codespace to collaborate in real-time.