Connecting Your Editor to the nREPL Server

Start the nREPL server

The following instructions are assumed to be executed in Notebook cells running the Basilisp Kernel, as indicated by the [n]: prefix.

First load the nREPL server namespace

[n]: (require '[basilisp-kernel.nrepl-server :refer [server-start]])

Then, you can start the nREPL server

• Specify a fixed port with :port

[n]: (def server (server-start {:port 9998})) 
nREPL server started on port 9998 on host 127.0.0.1 - nrepl://127.0.0.1:9998
#'user/server

• Use a random available port

[n]: (def server (server-start {})) 
nREPL server started on port 54482 on host 127.0.0.1 - nrepl://127.0.0.1:54482
#'user/server

Connect to the nREPL Server

Note

While it’s not necessary to open the project in your editor to connect to the nREPL server, doing so simplifies setup.

If you're not working on a specific project, you can create an empty basilisp.edn file next to your Basilisp notebook to get you started.

Open the basilisp.edn file in the root of your project to enable Clojure-specific features in your editor.

Then use your Editor's Clojure nREPL commands to connect to the server.

Both Emacs/CIDER and VSCode/Calva offer explicit support for Basilisp.

To connect

CIDER (Emacs)

1. Run M-x cider-connect-clj.
2. Select localhost.
3. Enter the port number from the nREPL server output.

Calva (VSCode)

1. Press Ctrl-Shift-P to open the Command Palette.
2. Select Calva: Connect to a Running REPL Server, not in your project>basilisp.
3. Enter the port number from the nREPL server output.

---

Automatic port discovery

Alternatively, to simplify connection, configure the nREPL server to create a .nrepl-port file next to basilisp.edn. Editors can detect this file and automatically connect using the port it specifies.

• Using :dir

[n]: (def server (server-start {:dir "<path/to/project-directory-where-basilisp-edn-resides>"})) 
nREPL server started on port 54972 on host 127.0.0.1 - nrepl://127.0.0.1:54972
#'user/server

A .nrepl-port file should now be created in the project directory (<path/to/project-directory-where-basilisp-edn-resides>) containing the port number.

Connect through your editor

CIDER (Emacs)

1. Run M-x cider-connect-clj.
2. Select localhost.
3. Select the <project-dir>:<port number> option.

Calva (VSCode)

1. Press Ctrl-Alt-P to open the Command Palette.
2. Select Calva: Connect to a Running REPL Server, in your project>basilisp.
3. The editor will automatically find the port using .nrepl-port.

The Editor should now connect seamlessly to the nREPL server.