A self-paced or facilitated workshop that enables you to get your hands dirty with Fulcro to experience and "get" this unique, full-stack web framework for Clojure. Originally presented at re:Clojure 2021.

Fulcro is unique among Clojure web frameworks in providing a complete, integrated, full-stack solution for creating non-trivial web applications. It is based on a few simple ideas with far-reaching consequences, it is unusually malleable, and we love it for its focus on creating maintainable, developer-friendly code.

In this workshop you will get a brief introduction to Fulcro and then get your hands dirty exploring the concepts in practice on an existing application in a series of guided exercises. We will use the excellent Fulcro Inspect tooling and mess up with the code.

You can find the workshop materials here, including:

• Course introduction
• Instructor's manual
• Student exercises

You can do this workshop on your own - perform the setup linked above, watch the minimalist introduction to Fulcro, and then follow the instructions and do the exercises. If you run into any issues or need help, use this repository's discussions or issues and/or reach out to @holyjak in the Clojurians Slack. I am also making a video of me doing the exercises, accompanied by a commentary, which will be available for $10 (to cover some of the costs of making this workshop) - get in touch if you are interested.

I can also facilitate this workshop for you or your company, see my business site for details and get in touch.

There are no "hard" theoretical prerequisites other than general experience with Clojure development but it will help a lot if you:

• (Preferably) have an experience with ClojureScript
• Have an idea about how React works
• Have an idea about GraphQL

To do right now:

• Clone / download this repository to a directory on your computer
• Install Java, Clojure CLI tools, Node and npm
• In a Chromium browser such as Vivaldi or Chrome:
  • Install Fulcro Inspect
  • Install React Developer Tools
  • Restart the browser after you install the two plugins
  • Configure Chrome Development Settings:
    • Under "Console": "Enable Custom Formatters"
    • Under "Network": "Disable Cache (while devtools is open)"
• (Optional, recommended) Install VS Code with Calva
• Try to run the application and connect to its REPL as described below

An hour or so before the workshop:

• Have the application running as described below. Make sure you can see the To Do application in the browser. If not, follow the Troubleshooting instructions below. Open Dev Tools and verify that Fulcro Inspect is there.
• Set up your windows as described in the workshop instructions and have both these workshop and Fulcro intro opened in a browser tab:

It is preferable to run the app locally with Calva (see below) but if you run into some issues with the editor or tooling, you can run everything in the browser with a pre-configured virtual machine:

(Requires login via GitHub / GitLab / Bitbucket. Gitpod offers enough free usage time for this workshop.)

To make everyone's lives simpler, it is recommended that you use VS Code with Calva, no matter what is your preferred editor / IDE. You only need to know a few Calva keybindings to be sufficiently effective during the workshop.

(You can use your editor if you really prefer that but you are on your own if you run into any problems with that.)

To run the application using Calva:

• Make sure Node dependencies are installed. In the terminal, run npm install (or use yarn)
• In the menu View - Command Palette... - Calva: Start a Project REPL and Connect (aka Jack-In)
• Select shadow-cljs
• Select :todomvc for the aliases to launch with (Note that it is not enough to press enter on the item, you need to first press space or click the checkbox.)
• Wait a few seconds, then select :todomvc for the build to connect to
• Once you see the message [:todomvc] Build completed. in the Calva Jack-in terminal:
  1. Open the file src/fulcro_todomvc/server.clj (Go - Go to File...)
  2. Load the file by executing the command View - Command Palette... - Calva: Load current Current File and Dependencies
  3. Scroll down to the (comment ...) form and place the cursor in (http-server), then press alt+enter
     • This will evaluate the form (call the http-server function)
     • The web browser will open with your application

You can start the app, both the frontend build and the backend server, from the terminal, as described below. But it is preferable to use VS Code with Calva and start them from Calva, which will provide you with better code inspection capabilities.

# In a terminal (preferable: use Calva):
❯ npm install # or yarn install
❯ npx shadow-cljs watch todomvc

# In another terminal:
❯ clj -A:dev
Clojure 1.10.3
user=> ((requiring-resolve 'fulcro-todomvc.server/http-server))

Connect your editor to the browser REPL. In Calva, execute Calva: Connect to a Running REPL Server in the Project - select shadow-cljs - accept the default localhost:9000.

Shadow-cljs runs a number of things:

• 8181 the webapp, served by our server (see server.clj)
• 9000 shadow-cljs nREPL
• 9630 shadow-cljs UI including its Inspect

It is possible to participate using any IDE but I really implore you to bite the bullet and use Calva this one time (though I am normally Cursive user myself). I do not have the bandwidth to support people that run into issues with any other setup and inevitably the do, even though they are otherwise experts in their IDE of choice. You will not do anything fancy in the editor - you only need a single keybinding to eval a form (alt-enter) and the biggest editing you will do is changing one keyword to another.

• If the application does not work properly when you start it from Calva then try to start it manually from the terminal, as described above.
• Are there any errors from shadow-cljs? Look both in the Calva Jack-in Terminal at the bottom of VS Code (if you have closed it: View - Open View... - type terminal - you should see 3, where the third is the one you want, "1.1 Calva Jack-in: shadow-cljs") There is lot of output, including the following lines:

npx shadow-cljs -d cider/cider-nrepl:0.26.0 watch :todomvc
shadow-cljs - config: /some/path/to/fulcro-intro-wshop/shadow-cljs.edn
shadow-cljs - starting via "clojure"
[..]
shadow-cljs - server version: 2.15.5 running at http://localhost:9630
shadow-cljs - nREPL server started on port 9000
shadow-cljs - watching build :todomvc
[:todomvc] Configuring build.
[:todomvc] Compiling ...
[..]
[:todomvc] Build completed. (260 files, 0 compiled, 0 warnings, 11.01s)

• Look also into output.calva-repl for any problems. (You can re-open it by running Go - Go to File... - type output.calva-repl)
• Make sure that you actually use the shadow-cljs version declared in package.json (and not e.g. your older. global installation)
• Make sure that your Node version is compatible with the one in package.json - engines

• Fulcro Inspect is just a blank page - try a different Chromium-based browser (Chrome, Vivaldi). Right-click - Inspect inside Fulcro Inspect to look for errors in its Console. It can fail e.g. if it is not allowed to access localStorage.