Figwheel is a hot-reload development tool. We recommend using figwheel sidecar so you can easily start the project from the command line or use it from the REPL support built into IntelliJ. The template already has the code for doing this. Part of it is in user.clj, and the other part is a simple script script/figwheel.clj to invoke it:

The README of your project describes how to start the various builds of your cljs code.

The most basic HTML file you can start with (and it won’t get much bigger) is:

Save this in resources/public/index.html.

You can now run this project in various ways.

From the command line:

Within IntelliJ:

• Run → Edit Configurations…​

• Press the '+' button, and choose Clojure REPL → Local

  • Give it a name (like dev)

  • Choose "Use clojure.main in normal JVM process" (important: it defaults to nREPL which won’t work right)

  • In JVM Args specify -Ddev. This is a trick of the template’s figwheel script that lets you pick one or more build from your build config easily. This selects just the dev build.

  • In Parameters add script/figwheel.clj

Now you should be able to start it from the Run menu.

For Emacs + Cider:

• Make sure a piggieback dev-time dependency and repl-option are in project.clj:

• With src/dev/user.clj open in a buffer, choose M-x cider-jack-in. In the clojure repl, run (start-figwheel), which will launch a cljs repl.

You should see the application printing "Hello World" at: http://localhost:3449

Now that you have a basic project working, let’s understand how to add some content!

Cached files can, as everywhere else, cause you lots of headaches. Fortunately they only really affect you poorly on the initial load in Fulcro. Hot reloads typically work very well.

One of the most maddening things that can happen during development is mystery around build errors. Nothing is more frustrating than not understanding what is wrong.

As you work on your code your compiler errors and warnings will show in the browser. DO NOT RELOAD THE PAGE! If you reload the page you’ll lose the warning or error, and that makes it harder to figure out what is wrong!

Instead, edit your code and re-save.

If you are having problems and you’ve lost your way, it is sometimes useful to ask figwheel to clean and recompile everything:

will typically get you back on track.

The basic code to build a simple component has the following form:

For our purposes we won’t be saying much about the React lifecycle methods, though they can be added. The basic intention of this macro’s syntax is to declare a component that can render UI and participate in our data-driven story.

This macro emits the equivalent of a React component with a render method.

The body of defsc is the render for the component and can do whatever work you need, but it should return a react element (see React Components, Elements, and Instances).

Luckily, there are factory methods for all of HTML5 in fulcro.client.dom. These functions generally take a Javascript map as their first argument (for things like classname and event handlers) and any children. There are two ways to generate the Javascript map: with the reader tag #js or with clj→js.

All versions of Fulcro:

Version 2.5 no longer requires the #js, the properties are optional, and they support an optional shorthand keyword for adding CSS class and DOM ids:

Fulcro 2.5+:

The 2.5 versions are macros that obtain the same runtime speed as the older versions in the most cases.

The reason this is necessary is that CLJS requires macros to be in CLJ files, but in order to get higher-order operation in CLJ the DOM elements must be functions. In CLJS, you can have both a macro and function with the same name, but this is not true in CLJ. Therefore, in order to get the optimal (inlined) client performance two namespaces are required.

React components receive their data through props and state (which is local mutable state on the component). In Fulcro we highly recommend using props for most things. This ensures that various other features work well. The data passed to a component can be accessed (as a cljs map) by calling prim/props on this, or by destructuring in the second argument of defsc.

So, let’s define a Person component to display details about a person. We’ll assume that we’re going to pass in name and age as properties:

Now, in order to use this component we need an element factory. An element factory lets us use the component within our React UI tree. Name confusion can become an issue (Person the component vs. person the factory?) we recommend prefixing the factory with ui-:

Now we can compose people into our root:

Part of our quick development story is getting hot code reload to update the UI whenever we change the source. Try editing the UI of Person and save. You should see the UI update even though the person’s data didn’t change.

You should already be getting the picture that your UI is going to be a tree composed from a root element. The method of data passing (via props) should also be giving you the picture that supplying data to your UI (through root) means you need to supply an equivalently structured tree of data. This is true of basic React. However, just to drive the point home let’s make a slightly more complex UI and see it in detail:

Replace your content with this:

So that the UI graph looks like this:

and the data graph matches the same structure, with map keys acting as the graph "edges":

This is certainly a possibility; however, it leads to other complications. What is the data model? How do you interact with remotes to fill your data needs? Fulcro has a very nice cohesive story for these questions, while other systems end up with complications like event handler middleware, coeffect accretion, and signal graphs…​not to mention that the sideband solution says nothing definitive about how you actually accomplish the server interactions with said data model.

Fulcro has a model for all of this, and it is surprising how simple it makes your application once you put your appliation together. Let’s look at the steps and parts:

All applications have some starting initial state. Since our UI is a tree, our starting state needs to somehow establish what goes to the initial nodes.

In Fulcro, there is a way to construct the initial tree of data in a way that allows for local reasoning and easy refactoring: co-locate the initial desired part of the tree with the component that uses it. This allows you to compose the state tree in exactly the same way as the UI tree.

The defsc macro makes short work of this with the initial-state option. Simply give it a lambda that gets parameters (optionally from the parent) and returns a map representing the state of the component. You can retrieve this data using (prim/get-initial-state Component).

It looks like this:

Now a lot of the specific data here is just for demonstration purposes. Data like this (people) would almost certainly come from a server, but it serves to illustrate that we can localize the initial data needs of a component to the component, and then compose that into the parent in an abstract way (by calling get-initial-state against that child).

There are several benefits of this so far:

1. It generates the exact tree of data needed to feed the initial UI.

2. That initial state becomes your initial application database.

3. It restores local reasoning (and easy refactoring). Moving a component just means local reasoning about the component being moved and the component it is being moved from/to: You remove the get-initial-state from one parent and add it to a different one.

You can see that there is no magic if you just pull the initial tree at the REPL:

It’s nothing more than function composition. The initial state option on defsc encodes your initial state into a function that can be accessed via get-initial-state on a class.

So behind the scenes Fulcro detects the initial state on the first mount and automatically uses it to initialize your application state.

By default, the entire initial state database is passed into your root node on render, so it is available for destructuring in Root’s props.

If you even want to see your current application state, you can do so through the atom that is holding your mounted application:

Let’s see how we program our UI to access the data in the application state!

Fulcro unifies the data access story using a co-located query on each component. This sets up data access for both the client and server, and also continues our story of local reasoning and composition.

Queries go on a component in the same way as initial state: as static implementations of a protocol.

The query notation is relatively light, and we’ll just concentrate on two bits of query syntax: props and joins.

Queries form a tree just like the UI and data. Obtaining a value at the current node in the tree traversal is done using the keyword for that value. Walking down the graph (a join) is represented as a map with a single entry whose key is the keyword for that nested bit of state.

So, a data tree like this:

would have a query that looks like this:

This query reads "At the root you’ll find :friends, which joins to a nested entity that has a label and people, which in turn has nested properties name and age.

• A vector always means "get this stuff at the current node"

• :friends is a key in a map, so at the root of the application state the query engine would expect to find that key, and would expect the value to be nested state (because maps mean joins on the tree)

• The value in the :friends join must be a vector, because we have to indicate what we want out of the nested data.

Joins are automatically to-one if the data found in the state is a map, and to-many if the data found is a vector. In the example above the :friends field from root pointed to a single PersonList, whereas the PersonList field :person-list/people pointed to a vector of Person. Be care that you don’t confuse yourself with naming (e.g. friends is plural, but points to a single list).

The namespacing of keywords in your data (and therefore your query) is highly encouraged, as it makes it clear to the reader what kind of entity you’re working against (it also ensures that over-rendering doesn’t happen on refreshes later).

You can try this query stuff out in your REPL. Let’s say you just want the friends list label. The function db→tree can take an application database (which we can generate from initial state) and run a query against it:

HINT: The mirror of initial state with query is a great way to error-check your work (and defsc does some of that for you): For each scalar property in initial state, there should be an identical simple property in your query. For each join of initial state to a child via get-initial-state there should be a query join via get-query to that same child.

Finally, we compose to Root:

This all looks like a minor (and useless) change. The operation is the same; however, we’re getting close to the magic, so stick with us. The major difference in this code is that even though the database starts out with the initial state, there is nothing to say we have to query for everything that is in there, or that the state has to start out with everything we might query for in the future. We’re getting close to having a dynamic data-driven application.

Notice that everything we’ve done so far has global client database implications, but that each component codes only the portion it is concerned with. Local reasoning is maintained. All software evolution in this model preserves this critical aspect.

Also, you now have application state that can evolve (the query is running against the active application database stored in an atom)!

1. A function acting in as a stand-in for our real delete

2. Adding the callback into the props (WRONG)

3. Pulling the onDelete from the passed props (WRONG). The query has to be changed to a lambda to turn off error checking to even try this method.

4. Invoking the callback when delete is pressed.

This method of passing a callback will work initially, but not consistently. The problem is that we can optimize away a re-render of a parent when it can figure out how to pull just the data of the child on a refresh, and in that case the callback will get lost because only the database data will get supplied to the child! Your delete button will work on the initial render (from root), but may stop working at a later time after a UI refresh.

There is a special helper function that can record the computed data like callbacks onto the child that receives them such that an optimized refresh will still know them. There is also an additional (optional) component parameter to defsc that you can use to deconstruct them:

1. The prim/computed function is used to add the computed data to the props being passed.

2. The child adds an additional parameter, and pulls the computed data from there. You can also use (prim/get-computed this) to pull all of the computed props in the body.

Now you can be sure that your callbacks (or other parent-computed data) won’t be lost to render optimizations.

Every change to the application database must go through a transaction processing system. This has two goals:

• Abstract the operation (like a function)

• Treat the operation like data (which allows us to generalize it to remote interactions)

The operations are written as quoted data structures. Specifically as a vector of mutation invocations. The entire transaction is just data. It is not something run in the UI, but instead passed into the underlying system for processing.

You essentially just "make up" names for the operations you’d like to do to your database, just like function names. Namespacing is encouraged, and of course syntax quoting honors namespace aliases.

is asking the underlying system to run the mutation ops/delete-person (where ops can be an alias established in the ns). Of course, you’ll typically use unquote to embed data from local variables:

When a transaction runs in Fulcro it passes things off to a multimethod. The multi-method is described in more detail in the section on the mutation multimethod, but Fulcro provides a macro that makes building (and using) mutations easier: defmutation.

The template application comes with a pre-built namespace for these src/main/app/api/mutations.cljs, but you can put them anywhere as long as the namespace in question is required by your application at runtime. Note there is also a mutations.clj, which is for the server-side handling of these same mutations.

A mutation looks a bit like a method. It can have a docstring, and the argument list will always receive a single argument (params) that will be a map (which then allows destructuring).

The body looks a bit like a letfn, but the names we use for these methods are pre-established. The one we’re interested in at the moment is action, which is what to do locally. The action method will be passed the application database’s app-state atom, and it should change the data in that atom to reflect the new "state of the world" indicated by the mutation.

For example, delete-person must find the list of people on the list in question, and filter out the one that we’re deleting:

1. The argument list for the mutation itself

2. The thing to do, which receives the app-state atom as an argument.

Then all that remains is to change basic-ui in the following ways:

1. Add a require and alias for app.operations to the ns

2. Change the callback to run the transaction

1. The require ensures that the mutations are loaded, and also gives us an alias to the namespace of the mutation’s symbol.

2. Running the transaction in the callback.

Note that our mutation’s symbol is actually app.api.mutations/delete-person, but the syntax quoting will fix it. Also realize that the mutation is not running in the UI, it is instead being handled "behind the scenes". This allows a snapshot of the state history to be kept, and also a more seamless integration to full-stack operation over a network to a server (in fact, the UI code here is already full-stack capable without any changes!).

This is where the power starts to show: all of the minutiae above is leading us to some grand unifications when it comes to writing full-stack applications.

But first, we should address a problem that many of you may have already noticed: The mutation code is tied to the shape of the UI tree!!!

This breaks our lovely model in several ways:

1. We can’t refactor our UI without also rewriting the mutations (since the data tree would change shape)

2. We can’t locally reason about any data. Our mutations have to understand things globally!

3. Our mutations could get rather large and ugly as our UI gets big

4. If a fact appears in more than one place in the UI and data tree, then we’ll have to update all of them in order for things to be correct. Data duplication is never your friend.

                                 +-------------------------------------+
                                 |                                     |
PersonList                       |     Person                          |
+---------------------------+    |     +----------------------------+  |
| ID  | Label               |    |     |ID | Name         | List ID |  |
|---------------------------|    |     |----------------------------|  |
| 1   | Friends             |<---+     |1  | Joe          |    1    |--+
+---------------------------+          |----------------------------|  |
                                       |2  | Sally        |    1    |--+
                                       +----------------------------+

PersonList                             Person
+---------------------------+          +------------------+
| ID  | Label   | People    |          |ID | Name         |
|---------------------------|          |------------------|
| 1   | Friends | #{1,2}    |----+---->|1  | Joe          |
+---------------------------+    |     |------------------|
                                 +---->|2  | Sally        |
                                       +------------------+

Fortunately, you don’t have to hand-normalize your data. The components have almost everything they need to do it for you, other than the actual value of the Ident. So, we’ll add one more option to your components (and we’ll add IDs to the data at this point, for easier implementation):

The program will now look like this:

1. Adding an ident allows Fulcro to know how to build a FK reference to a person (given its props). The first element is the table name, the second is the name of the property that contains the ID of the entity.

2. We will be using IDs now, so we need to add :db/id to the query (and props destructuring). This is just a convention for the ID attribute

3. The state of the entity will also need the ID

4. The callback can now delete people by their ID, which is more reliable.

5. The list will have an ID, and an Ident as well

If you reload the web page (needed to reinitialize the database state), then you can look at the newly normalized database at the REPL:

Note that db→tree understands this normalized form, and can convert it (via a query) to the proper data tree. db→tree (for legacy reasons) requires a way to resolve references (idents) and the database. In Fulcro these are the same. So, try this at the REPL:

We have now made it possible to fix the problems with our mutation. Now, instead of removing a person from a tree, we can remove a FK from a TABLE entry!

This is not only much easier to code, but it is completely independent of the shape of the UI tree:

1. References are always idents, meaning we know the value to remove from the FK list

2. By defining a function that can filter the ident from (1), we can use update-in on the person list table’s people.

3. This is a very typical operation in a mutation: swap on the application state, and update a particular thing in a table (in this case the people to-many ref in a specific person list).

If we were to now wrap the person list in any amount of additional UI (e.g. a nav bar, sub-pane, modal dialog, etc) this mutation will still work perfectly, since the list itself will only have one place it ever lives in the database.

It is good to know how an arbitrary tree of data (the one in InitialAppState) can be converted to the normalized form. Understanding how this is accomplished can help you avoid some mistakes later.

When you compose your query (via prim/get-query), the get-query function adds metadata to the query fragment that names which component that query fragment came from.

For example, try this at the REPL:

The get-query function adds the component itself to the metadata for that query fragment. We already know that we can call the static methods on a component (in this case we’re interested in ident).

So, Fulcro includes a function called tree→db that can simultaneously walk a data tree (in this case initial-state) and a component-annotated query. When it reaches a data node whose query metadata names a component with an Ident, it places that data into the approprite table (by calling your ident function on it to obtain the table/id), and replaces the data in the tree with its FK ident.

Once you realize that the query and the ident work together to do normalization, you can more easily figure out what mistakes you might make that could cause auto-normalization to fail (e.g. stealing a query from one component and placing it on another, writing the query of a sub-component by-hand instead of pulling it with get-query, etc.).

A relatively recent (late 2017) addition to the ecosystem is Fucro Inspect. A set of tools you can load into your environment during development. In fact, the template already has them (for the dev build)! On OSX or Linux, simply hit CTRL-F. See Fulcro Inspect’s documentation for how to set the keyboard shortcut in Windows.

The DB tab of this tool shows you your application’s database and has a time slider to see the history of states! It also has tabs for showing you transactions that have run, and network interactions. See the tool’s documentation for more information. In fact, by the time you read this it will probably have even more exciting features!

There is a build in the template project called cards. This starts up a development environment where you can code entire applications (or portions of them) in an environment that can show you live state and is quite handy, particularly for working with small parts of your program (remember, we can actually split off chunks of the application because they are all relative to their parent).

You can start this build just as we did near the start of this guide, and load it via http://localhost:3449/cards.html.

In fact, you don’t even have to start a new REPL! You can run switch-to-build:

Then you can embed a full-funcional Fulcro application into a card environment with very little code. Replace the content of src/cards/app/intro.cljs with:

save and go to http://localhost:3449/cards.html#!/app.intro. You should see your app running in a card, and you should be able to see the live database (which will change as you interact)!.

You can always hand-build a server in Fulcro, but the fulcro.easy-server is a great option for getting started.

The template generates the easy one for you in src/main/app/server.clj.

It is very handy to be able to look at your application’s state to see what might be wrong. We’ve been manually dumping application state at the REPL using a rather long expression. So, at this point make sure you are either running your application in a devcard, or you know how to look at things with Fulcro Inspect. The output in the devcards is typically easier for beginners to read.

Now we will start to see more of the payoff of our UI co-located queries and auto-normalization. Our application so far is quite unrealistic: the people we’re showing should be coming from a server-side database, they should not be embedded in the code of the client. Let’s remedy that.

Fulcro provides a few mechanisms for loading data, but every possible load scenario can be done using the fulcro.client.data-fetch/load function.

It is very important to remember that our application database is completely normalized, so anything we’d want to put in that application state will be at most 3 levels deep (the table name, the ID of the thing in the table, and the field within that thing). We’ve also seen that Fulcro can also auto-normalize complete trees of data, and has graph queries that can be used to ask for those trees.

Thus, there really are not very many scenarios!

The three basic scenarios are:

• Load something into the root of the application state

• Load something into a particular field of an existing thing

• Load some pile of data, and shape it into the database (e.g. load all of the people, and then separate them into a list of friends and enemies).

Let’s try out these different scenarios with our application.

First, let’s correct our application’s initial state so that no people are there:

If you now reload your page you should see two empty lists.

Mutations are handled on the server using the server’s defmutation macro (if you’re using Fulcro’s built-in request parser).

This has the identical syntax to the client version!

So, this is really why we have a duplicated namespace in Clojure called mutations.clj right next to our mutations.cljs.

So, let’s add an implementation for our server-side delete-person. Your mutations.clj should end up looking like this (don’t forget the require to get access to the people db):

Refresh the code on your server with (restart) at the REPL. However, don’t expect it to work just yet. We have to tell the client to send the remote request.

For this example we’re going to use the following public REST API endpoint: http://jsonplaceholder.typicode.com/posts which returns a list of posts (try it to make sure it is working).

It should return an array of JSON maps, with strings as keys.

Basically, when you run a transaction (read or write) the raw transaction that is intended to go remote is passed into the send method of a networking protocol. The networking can send that unchanged, or it can choose to modify it in some way. Since REST servers don’t understand our Fulcro requests, we have to add a layer at the network to convert one to the other, and back (for the response).

First, let’s talk about the UI code for dealing with these posts, since the UI defines the queries. Here is a very simple UI we can add to our program:

1. A component to represent the post itself

2. A component to represent the list of the posts

3. Composing the Posts UI into root query

4. Composing the Posts UI into root initial data

5. Pull the resulting app db data from props

6. Render the list

Of course, there are no posts yet, so all you’ll see is the heading. Notice that there is nothing new here. The UI is completely network agnostic, as it should be.

Now for the networking code. This bit is a little longer, but most of it is the details around network communcation itself, rather than the work you have to do. Create a new namespace src/main/app/rest.cljs:

The steps you need to customize are annotated in the comments of the code. There are just a few basic steps:

1. Fulcro comes with a handy function that can convert a query into an AST, which is easier to process. We don’t really care too much about the whole query, we just want to detect what is being asked for (we’re going to ask for :posts).

2. Once we’ve understood what is wanted, we create a REST URL and GET the data from the REST server.

3. When we get a successful response we need to convert the JSON into the proper EDN that the client expects. In this case we’re looking for { :posts [ {:db/id 1 :post/body "…​" :post/title "…​" ] …​ }.

4. Once we have the properly structure tree of data to match the query, we simply pass it to the ok callback that our send was given.

In a more complete program, you’d put hooks at steps (2) and (3) to handle all of the different REST requests, so that the majority of this code would be a one-time thing.

Fulcro lets you set up networking yourself. We’d still like to talk to our server, but now we also want to be able to talk to the REST server. The modification is done in our client options. For example, our devcard playground could be changed to this:

IMPORTANT NOTE: If you’re using the dev cards, you might want to change :inspect-data true to false. Devcards get a bit slow if you put a lot of data in the app and ask the card to format it all in the inspector. In those cases it can be better to use Fulcro Inspect instead).

All the hard stuff is done. Loading is now triggered just like you would have before, except with a :remote option to specify which network to talk over:

The same technique is used. Everything you’ve read is accurate for mutations as well (you’ll see the mutation come into the send function). To trigger a mutation, just add another section to your client mutation (a mutation can be sent to any number of remotes, in fact):

So, action names the local (optimistic) effect. Each other method name must match a remote’s name as configured in the :networking of the client. If you return true (or an AST) from one of these "remote" sections, it will trigger the mutation to be sent to that network handler.