First up: you can prepare for all this without getting access to Codespaces because it’s basically VSCode in the cloud. You can use your local VSCode and be ready to go when GitHub is :) Also since Codespaces is a chargeable feature, I expect it will make sense to run on your local platform if you have one and in the cloud if you’re on another device.
Get the Remote – Containers extension for VSCode installed to begin. This uses a standard devcontainer configuration to describe the docker platform that your project runs on. This is useful when you have a lot of projects, a lot of developers, and therefore many platforms to manage. Now I’ve seen it, I’ll be adding it to plenty of my projects!
To add this sort of setup to an existing project, go and rummage in the vscode-dev-containers repo in the
containers folder for something that would fit your stack, or at least give you a starting point. You’re looking for a
.devcontainer folder that you will copy, wholesale, into your own project. This will contain some dockery things, maybe a README with specific instructions (although all the files seem to be really well commented which I always appreciate), and the all-important
devcontainer.json file that describes to VSCode how the whole thing is going to fit together. Copy it in (or use the Remote – Containers plugin to do this for you), and configure as desired for your setup.
Once the devcontainer is set up, opening the project in VSCode will cause you to be prompted whether you want to re-open the project in the container.
Pro tip: the
vscode-dev-containers repo README also has links to some “try it” projects for common stacks that I found useful.
There’s another piece of the puzzle but again it’s VSCode-specific: the launch configuration for your project. I’m not sure why it’s described as “debugging” because I think this is how I make the project run. I’m fairly new to VSCode though so please add advice in the comments!
The launch configuration lives in
.vscode/launch.json. This is a great way to share this information but check if
.vscode/ is included in the project’s
.gitignore file – I would not normally advocate including proprietary-tool-specific settings in a repo but here we are! The simplest way to get started seems to be to press the “Debug” button without any configuration in place, and VSCode will hold your hand through the process.
With the launch config in place, you should be able to “Debug” your project and something should … happen!
When you get access to the Codespaces feature, you’ll probably notice the “Codespaces” item that appears on the top menu between “Pull Requests”/”Issues” and “Marketplace”. You will also see new options popping up: The Code download/clone button includes the option to open the project in a codespace, and pull requests will also have a new option under their “Open With” button.
This will provide you with:
* VSCode opens in the browser with the project or pull request in
* The devcontainer in this project gets spun up (be patient!)
* When you “Run” our “Debug” the project, you’ll get a notification when the server is ready. You can even Ctrl+Click to open the “localhost” addresses which are then rewritten to your new cloud workspace URLs
The convenience makes the whole thing compelling and I imagine I’ll have this set up on many of my own projects. However I feel a word of caution is appropriate here. Git is an open standard; GitHub is just one option for a hosted interface to go with git. No project should require use of a specific tool, even a lovely and widely-used one like VSCode. I’m a Linux user with accessibility needs; anything that dictates the tools I use locally is a non-starter (I can’t imagine actually working with Codepsaces, it’s just a nice way of including other people or quickly testing something from the train on a mobile device).
If you take one thing away, I’d love it to be this: Let’s pledge to include these features in our projects, and to include the “standard” usage/install/contributing instructions too. It’s a Docker file and some commands to run, no special equipment required.
Also published on Medium.