A VS Code Extension Template. Or an automated VS Code extension development workflow, with support for coding, building, testing, end-to-end testing, and publishing the extension to the VS Code Marketplace and the Open VSX Registry.
The workflow is powered by Interactive Programming. You can use the extension while you are hacking on it, without reloading the extension host. The feedback is instantaneous. As it should be to keep coding productive and maximum fun.
It is probably for you. 😄 Especially if you would like to build an extension for VS Code. Also if:
- You want to explore what it takes to publish an extension to the VS Code Marketplace in an automated manner.
- Like to have the plumbing for testing, including end-to-end testing, in place from the get-go, ready for you to fill in as you build your extension
- You would like to learn Clojure/ClojureScript in a fun way
- Interactive Programming is your thing
- You think that Interactive Programming might be your thing
The tools you need to get started are:
- VS Code
- Node.js
- Java
- Clojure CLI
- Babashka
- If you plan to publish your extension: At least a skim through Microsofts Publishing extensions guide and one skim through the corresponding Publishing Extensions guide for open-vsx.
Add your curiosity and you should be good to go. To just try the template/workflow out, you do not need to know any ClojureScript (or even programming). When you start to try make the extension do something interesting, you will need to know some Clojure/ClojureScript. Learning Clojure will be a fun endeavor, I promise.
On Github Use this template, and name your repository, say you are full of imagination and name it my-extension. Clone your repo and open it in VS Code.
You may want to wait with renaming the extension itself until you've confirmed that you can compile and start it, and connect the REPL for development. When that's confirmed, renaming the extension is mainly a matter of a global search and replace in the project. Something like so:
- Make a global search (cmd/ctrl+shift+f) for
vsc-et. Activate case sensitivity and whole-word matching for precision. Study the results, removing the ones you don't think apply (I think it's safe to replace all occurrences). Expand the replace input and study the results list some more before clicking the Replace All button.- Make a global search replace of “Extension Template”, similarly case sensitive and matching whole words.
- The publisher of the extension template is
betterthantomorrow, which you will need to change if you are to publish your extension to the marketplace. See above under prerequisites for the guides to go through to get your publisher id.
... and connecting the ClojureScript REPL.
The paved path is:
- cmd/ctrl+shift+b. This starts the default build task, which is configured (in .vscode/tasks.json to start Clojure with an nREPL server. This will happen in a terminal named Build+watch extension.
- Wait for it to report something like:
nREPL server started on port 56749 on host localhost - nrepl://localhost:56749
- Wait for it to report something like:
- ctrl+alt+c ctrl+alt+c. This runs the command: Calva: Connect to a Running REPL Server in the Project
- It will connect the Clojure REPL, start a ClojureScript (shadow-cljs) REPL, and build the extension.
- This will compile the extension and run the tests. Wait for the Build+watch extension to show that the tests have ran, and for Calva to pop up a progress dialog looking something like so:
- Hint: The ClojureScript app is your extension.
- F5. This starts the VS Code Development Extension Host (because configured to do so in .vscode/launch.json)
- The development extension host is a VS Code window where your extension under development is installed. You now need to activate it to actually start the ClojureScript app.
- In the extension development host cmd/ctrl+shift+p, find and run the command Extension template: Say hello!
- This activates your extension and starts the ClojureScript app and its REPL
- Back in the development project you will see the progress dialog go away. Because now the development project window is connected to the Development Extension Host window's REPL.
- Now you can hack on the extension code, which will update the app in the extension host window while it is running (a.k.a. interactive programming).
The important thing to note here is the steps where you activate your extension in the development host, starting the ClojureScript repl which Calva can connect to. Depending on the extension you build, it may be that it activates automatically, or by some specific file appearing or whatever. The point is that your extension needs to be activated for Calva to connect to it, and that starting the development host is often not enough to start your extension.
TBD...
Thus possibly involves carrying out the steps at create your own organization
TBD...
My name is Peter Strömberg, a.k.a. PEZ. I love Clojure and VS Code, and I love to build things. I created Calva, an extension for working with Clojure in VS Code. I also co-created Joyride, a scripting environment for VS Code that lets you extend the editor in user space (i.e. without creating an extension). I've also created Paste Replace, and a whole bunch of Joyride scripts, big and small (mostly small).
I created this template because I want to share what I have figured out about building and maintaining extensions for VS Code. To me it is the most fun and rewarding way to spend my time, and I want you to have as much fun as I get. 😄 Calva is mostly built with TypeScript, and I'd like to contribute to you building your extensions in a more civilized programming language. Because ClojureScript is much, much, more fun than TypeScript.
That said, the workflow and automation used in the template are used for Calva, as well as with my pure ClojureScript extensions, so if you find the rest of the automation in this template useful, you can most definitely use it with a TypeScript tool chain.
MIT
Free to use, modify and redistribute as you wish. 🍻🗽
That, said, you are welcome to show me you like my work using this link: