This is an official template for a Fulcro starter project that might go on to become a production application. It includes a number of features that a beginner will not need for just playing with the library (full CI test setup, workspaces), but is simple enough that a beginner should have no real problem using it.
Beginners should therefore either use this template, or just generate simple play projects from the instructions in the Developer’s Guide.
Fulcro also has a Rapid Application Development add-on that makes building a production application faster and easier; however, a beginner should not start with RAD except to satisfy surface-level curiosity. RAD requires that you understand the core library (even though most of it uses convention and configuration over actual code). If you understand Fulcro and are working on a real production application then you should probably consider using the setup from the Fulcro RAD demo as starting point instead of this template.
RAD gives you a lot of leverage for a new project, and includes a number of pre-written patterns written in Fulcro. It includes very good HTML5 routing, form/report support. It does not limit your options, just expands what you have available by default.
This template includes a server with a mock database and CSRF protection and a client with login. It also integrates Nubank Workspaces for a visual, interactive development environment for Fulcro components, which you can choose to use. Both backend Clojure and frontend ClojureScript REPLs are configured and started. There are also sample frontend tests.
The server code leverages Mount to make it easy to start and to reload changes - see
the helper functions in src/dev/development.clj
.
Client hot code reloading is handled automatically by shadow-cljs.
The main project source is in src/main
, the frontend code in .cljs
files in app.*
and app.ui.*
.
Dependency Aliases:
You will want to enable the :dev
dependency while developing this project. In IntelliJ this is in the
"Clojure Deps" border tab window under "Aliases".
This is a manual to get started with this example project.
It comes with helper npm run
scripts pre-loaded, you can find them in the package.json file.
Typically you want to start the server and the main and/or workspaces (if you decided to use Nubank Workspaces) client builds. See below. You can simply start everything from the command line
git clone --depth 1 -o fulcro-template https://github.com/fulcrologic/fulcro-template.git fulcro-app
cd fulcro-app
# The shadow-cljs compiler is a dependency.
yarn install
# 1. Start shadow-cljs frontend compilation server:
npx shadow-cljs server
# 2.: Visit the shadow-cljs compile server UI at http://localhost:9630
# and enable the "main" and optionally "workspaces" builds
# 3. Start the backend server:
# (Note: for proper development you will want to start it in a nREPL-based
# REPL, see the detailed instructions for "The API Server" below.)
clj -A:dev -J-Dtrace -J-Dguardrails.enabled=true
user=> (require 'development)
user=> (in-ns 'development)
development=> (start)
# after modifications of the backend code run: `(restart)`
# 4. Visit the application at http://localhost:3000
# (Optional): Visit the Workspaces UI at http://localhost:3000/wslive.html
# (Optional): Run tests via `npm run client/test` and visit http://localhost:8022
You can find the UI of the frontend compile server here: http://localhost:9630 There you can kick off the compilation of the other targets.
-
Open and connect your nREPL to localhost:9000.
-
Execute
(shadow/repl :main)
. (you can select another target of course)
The instructions provided above do not start a REPL server for the backend, only a simple interactive REPL session. See the The API Server section below to learn how to start the server from a nREPL REPL that you can connect your editor to.
If you choose to use Workspaces, you have two options,
you can run them with the actual backend as described in the Quick Start above
or you can run only the frontend part (communication with the backend will fail due to CSFR):
npm run client/workspaces
and visit http://localhost:8023
Have a look at src/workspaces
.
The shadow-cljs compiler uses all js dependencies through
NPM. If you use a library that is in cljsjs you will also have to add
it to your package.json
.
You also cannot compile this project until you install the ones it depends on already:
$ yarn install
Adding NPM Javascript libraries is as simple as adding them to your
package.json
file and requiring them! See the
the Shadow-cljs User’s Guide
for more information.
Shadow-cljs handles the client-side development build. The file
src/main/app/client.cljs
contains the code to start and refresh
the client for hot code reload.
In general it is easiest just to run the compiler in server mode:
$ npx shadow-cljs server
INFO: XNIO version 3.3.8.Final
Nov 10, 2018 8:08:23 PM org.xnio.nio.NioXnio <clinit>
INFO: XNIO NIO Implementation Version 3.3.8.Final
shadow-cljs - HTTP server for :test available at http://localhost:8022
shadow-cljs - HTTP server for :workspaces available at http://localhost:8023
shadow-cljs - server version: 2.7.2
shadow-cljs - server running at http://localhost:9630
shadow-cljs - socket REPL running on port 51936
shadow-cljs - nREPL server started on port 9000
...
then navigate to the server URL (shown in this example as http://localhost:9630) and use the Builds menu to enable/disable whichever builds you want watched/running.
Shadow-cljs will also start a web server for any builds that configure one. This template configures one for workspaces (if running without the Clojure backend is enough for you), and one for tests:
-
Workspaces (without backend): http://localhost:8023
-
Workspaces (with the backend; start it first!): http://localhost:3000/wslive.html
-
Tests: http://localhost:8022
See the server section below for working on the full-stack app itself.
The shadow-cljs compiler starts an nREPL. It is configured to start on
port 9000 (in shadow-cljs.edn
).
In IntelliJ: add a remote Clojure REPL configuration with
host localhost
and port 9000
.
then:
(shadow/repl :main)
will connect you to the REPL for a specific build (NOTE: Make sure you have a browser running the result, or your REPL won’t have anything to talk to!)
If you’re using CIDER
see the Shadow-cljs User’s Guide
and the comments in deps.edn
for more information.
In order to work with your main application you’ll want to start your own server that can also serve your application’s API.
Start a LOCAL clj nREPL in IntelliJ (using IntelliJ’s classpath with
the dev
alias selected in the Clojure Deps tab), or from the command line:
$ clj -A:dev -J-Dtrace -J-Dguardrails.enabled=true
user=> (require 'development)
development=> (in-ns 'development)
development=> (start)
development=> (stop)
...
development=> (restart) ; stop, reload server code, and go again
development=> (tools-ns/refresh) ; retry code reload if hot server reload fails
The -J-Dtrace
adds a JVM argument that will enable performance tracing for Fulcro Inspect’s network tab so you can
see how your resolvers and mutations are performing.
The -J-Dguardrails.enabled=true
turns on guardrails instrumentation of guardrails spec’d functions, which is a wrapper
of Clojure spec that makes instrumentation and production-time elision (for performance and size) much easier.
ℹ️
|
For real development, please use an editor that has REPL integration, like Cursive (recommended) or Spacemacs. |
The URL to work on your application is then http://localhost:3000.
Hot code reload, preloads, and such are all coded into the javascript.
There is a preload file that is used on the development build of the
application app.development-preload
. You can add code here that
you want to execute before the application initializes in development
mode.
Tests are in src/test
. Any test namespace ending in -test
will be auto-detected.
src/test
└── app
└── sample_test.cljc spec runnable by client and server.
You can write plain deftest
in here, and it is preconfigured to support the helper macros in fulcro-spec
as well.
Typically you’ll just run your tests using the editor of choice (e.g. Run tests in namspace in IntelliJ).
The tests are also set up to run with Kaocha at the command line for your convenience and CI tools:
$ clj -A:dev:clj-tests --watch
See the Kaocha project for more details.
The tests can be run in any number of browsers simply by navigating to the test URL that shadow-cljs outputs.
CI support is done through the ci-test
build in shadow, and via Karma.
If you start the ci-tests
build in Shadow-cljs, then you can also run cljs tests in a terminal "watch mode"
with:
npx karma start
Of course, this make CLJS CI easy:
npx shadow-cljs compile ci-tests
npx karma start --single-run
Workspaces is a project by Nubank that is written in Fulcro, and has great support for developing in Fulcro. It is similar to devcards but has a more powerful user interface, integration with Fulcro Inspect, and much more.
The source directory for making additions to your workspace is src/workspaces
.
❗
|
Any namespace ending in -ws will be auto-detected and added to your workspace!
|
This instance of the template uses tools.build now that depstar has been archived.
First we need to add the ability to use tools.build by adding in deps.edn
a new :alias
called :build
. In this case we use v0.9.4
because that’s the most recent version, but you should probably use whatever the most recent stable version is.
:build {:deps {io.github.clojure/tools.build {:git/tag "v0.9.4" :git/sha "76b78fe"}}
:ns-default build}
According to the clojure website, the :ns-default specifies the default Clojure namespace to find the function specified on the classpath.
Next, we need to add the build.clj
file. Looking at the prior links, they’ll explain in more detail the different sorts of functions you can add. The nice thing about tools.build is that it operates like other clojure code. When you write a function in this file, you can run it via the cli, and you know exactly what you’re running (at least at the top level).
In our build file we just have two functions, clean
and uber
. All clean does is remove the target directory. Uber on the other hand is a function we can use to build an uberjar. Again, refer to the prior links for more detail about what these functions are doing specifically (or just look at the functions yourself!).
To run a build command, we can just write
clj -T:build <function>
e.g.
clj -T:build clean
or
clj -T:build uber
All this is doing is running our defn
functions in the build file!
Once you run the uber command, it should generate a jar in the target
directory, but you’ll need to make sure it doesn’t generate any errors first. Once you’ve had one successfully generated you can then run the jar to test that it’s working!
You can do that by running
java -jar target/<jar name>
Then, hopefully, it should spin up the server. Don’t forget to compile and release your shadow-cljs frontend code first. Once you’ve run the jar, it should spin up an http server, at which point you can hit the index file to check that your code is running. In our case in our prod.edn
file we’ve set the port to 8080
so we’ll want to navigate to localhost:8080/index.html. If all has gone well, you now have a running production uberjar of your application. Yay!