Fulcro Developers Guide

Many of the code examples assume you’ve required the proper namespaces in your code. This book adopts the following general set of requires and aliases:

others will be identified as they are used.

The next chapter, "Getting Started", is an exception. The code you see in that chapter is meant to be added to a template that you create and run on your own machine.

The Fulcro template uses shadow-cljs. We’ve been using this tool for over a year and it is a really great experience. The additions over the stock Clojurescript compiler make for a much more polished experience. It allows you to use the normal js ecosystem of components very easily, is really good about caching, doesn’t get easily confused (I almost never have to do a clean of project builds, which I used to have to do with the standard tools all the time). You should check out the User’s Guide when you have a chance, but for now you can simply start the compiler server:

and navigate to the URL it prints out for the compiler server (usually http://localhost:9630). You can then use the "Builds" menu to turn on/off different client builds and see the progress live as it happens!

It also has hot-code reload built in, so there is no need for an additional tool like figwheel.

Simply start a REPL (see the README in your generated project for instructions) and use:

to start the server (which defaults to port 3000). If you’ve turn on the main build in shadow-cljs, then you should see the base template page. Please refer to the README in your template app if this doesn’t work, as this could get out of date with respect to the template.

Fulcro supports React 15 and 16 (and should even be fine with 17 when it is released). The template uses shadow-cljs for compiles, so you simple include the version you’d like to use in the standard package.json file. This is already done for you in the template.

Your HTML file to load the app needs these things:

This corresponds to:

but you won’t find this in your template resources. The template generates a secure app with CSRF (cross-site request forgery) protection. This means a CSRF token needs to be embedded in the page, and this is a complication you can ignore for the most part right now; however, it explains why we dynamically generate the HTML file in the server using hiccup (in middleware.clj):

REMINDER: When developing it is a good idea to: Use Chrome (the devtools only work there) and install the Fulcro Inspect extension from the Chrome store. Keep the developer’s console open, and in the developer console settings: "Network, Disable cache (while DevTools is open)", and "Console, Enable custom formatters".

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.

The Fulcro Inspect tab will show the state of your Fulcro application (along with lot of other useful details like your transaction log) if you’ve included the proper dependencies and preloads (which the template should have done for you).

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

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

Class names and IDs can be written in a more compact format instead of the map (or in front of it if you have other props to pass):

of course you can also :refer the common tags in your namespace declaration:

and make this even tighter:

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.

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). As of React 16 you can return a sequence of elements as well (though each must have a unique :key).

There are factory methods for all of HTML5 in fulcro.client.dom. These functions can take an optional keyword that specifies classes and an ID, followed by an optional map or additional props. If the tag allows children then they are simply placed after these two optional things:

These are macros that obtain very good runtime speed by converting the maps and such to low-level js at compile time.

The reason this is necessary is that CLJS requires macros to be in CLJ files, but in order to get higher-order functions to operate 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":

We don’t need it at the moment, but you may find it useful to note that any component that is required in your application will appear in a global component registry. You can look up such components using a symbol or keyword that matches the fully namespace-qualified name of the component:

This comes in handy for things like code splitting (where the dynamically loaded code will appear in the registry), tracking classes (by name) in app state (which cannot appear there as "code").

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 application 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:

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.

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. Beware 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)!

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:

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:

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.

Mutations typically can go wherever you want. The macro augments a multimethod, so you need to make sure that namespace is required by files that your program already uses. Something like src/main/app/api/mutations.cljs is fine, but you might also find it useful to place your mutations in something topical so you can write the server mutations in the CLJ version of the file, and the client ones in the cljs. Mutations are namespaced, so this makes things easier.

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:

Then all that remains is to change ui.root in the following ways:

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:

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:

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: It is much easier to look at this using Fulcro Inspect in your developer tools tab):

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:

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 appropriate 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.).

We’ve mentioned this before, but now that you know about the centralized database, we want to mention it again: Use it! 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 features.

There is a build in the template project called workspaces. This starts up a development environment where you can code components, full-stack elements, or even entire applications in a flexible environment. Remember, we can actually split off chunks of the application because they are all fed data via a normalized database and coupled only to their parent.

See the README of your template for instructions on using it.

The template generates a pretty complete server that uses ring-defaults and has CSRF protection configured.

The code in the template is pretty well documented, and it is mostly standard Ring stuff. The main part of interest is the wrap-api handler:

This generates a Fulcro query/mutation parser and sets it up to be called on some uri (which the server sets to /api).

Fulcro includes an EDN configuration file reader that allows for easy configuration of your server. It bases all configs on config/defaults.edn, and deep merges a runtime-selected EDN file over that so that each developer, test environment, or production system can make it’s own configuration changes.

Your template already has these in src/main/config. See your template content for their content.

The config/defaults.edn file is always looked for by the server (on CLASSPATH, so in your source or resources folder), and should contain all of the default settings you think you want independent of where the server is started.

The server (for safety reasons in production) will not start if there isn’t also a user-specified file containing potential overrides.

Basically, it will deep-merge the two and have the latter override things in the former. This makes mistakes in production harder to make. If you read the source of the config.clj file you’ll see that it defaults to development mode. If you look in server_main.clj (the production main) you’ll see this is overridden.

You can also override this with the JVM option -Dconfig=path-to-file. If the path is relative, it will look for it in application resources. If it is absolute, it will look for it on the disk:

This command-line option overrides any config file that was specified in the application itself (except for defaults.edn, which is always the base).

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:

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, 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.

Items are joined together into a graph using a tuple of the table name and the key of an entity. For example, the item above is known as [:person/by-id 4]. Notice that this tuple is also exactly the vector you’d need in an operation that would pull data from that entity or modify it:

These tuples are known as 'idents'. Idents can be used anywhere one node in the graph needs to point to another. If the idents (which are vectors) 'appear' in a vector, then you are creating a 'to-many' relation:

Notice in the example above that Joe and Julie point at each other. This creates a 'loop' in the graph. This is perfectly legal. Graphs can contain loops. The table in the example contains 4 nodes.

The client database treats the 'root' node as a special set of non-table properties in the top of the database map. Thus, an entire state database with 'root node' properties might look like this:

The above data structure is now a graph database that looks like this:

This makes for a very compact representation of a graph with an arbitrary number of nodes and edges. All nodes but the special "root node" live in tables. The root node itself is special because it is the storage location for both root properties and for the tables themselves.

The graph database on the client is the most central and key concept to understand in Fulcro. Remember that we are doing pure rendering. This means that the UI is simply a function transforming this graph database into the UI.

There are two primary things to write in Fulcro: the UI and the mutations. The UI pulls data from this database and displays it. The mutations evolve this database to a new version. Every interaction that changes the UI should be thought of as a data manipulation. You’re making a new state of the world that your pure renderer turns into DOM.

The graph format of the database means that your data manipulation, the main dynamic thing in the entire application, is simplified down to updating properties/nodes, which themselves live at the top of the state atom or are only 2-3 levels deep:

For the most part the UI takes care of itself. Clojure has very good functions for manipulating maps and vectors, so even when your data structures get more complex the task is still about as simple as it can be.

To avoid collisions in your database, the following naming conventions are recommended for use in the Fulcro client-side graph database:

Here are some common things you’ll want to know how to do that are different when rendering with Fulcro:

When you create a new client you can pass options directly to the reconciler with :reconciler-options. There are a number of options that are used internally by the higher-level layers of Fulcro and should not really be used directly, but there are a number of options that can be quite useful.

The reconciler does a number of things to optimize rendering beyond the basics of React.

The shouldComponentUpdate optimization reduces the render load by quite a bit, but running the query from root can be somewhat costly depending on how well you optimized your UI query. Thus, idents become a major factor in both normalization and rendering performance since Fulcro relies on them in order to reduce the query overhead of UI refresh. This isn’t something you typically need to remember, since you should be using idents on all components so they are easier to refactor and reuse.

Version 2.1+ of Fulcro include the ability to tell the reconciler which rendering mode to use.

The primary argument list contains the common elements you might need to use in the body:

The last parameter will let you destructure fulcro-css names, if and only if you’re using the Fulcro CSS library.

Only the first two parameters are required, so you can even write:

The core options (:query, :ident, :initial-state, :css, and :css-include) of defsc support both a lambda and a template form. The template form is shorter and enables some sanity checks; however, it is not expressive enough to cover all possible cases. The lambda form is slightly more verbose, but enables full flexibility at the expense of the sanity checks.

IMPORTANT NOTE: In lambda mode use this and props from the defsc argument list. So, for example, (fn [] [:x]) is valid for query (this is added by the macro), and (fn [] [:table/by-id id]) is valid for ident.

If you include :ident, it can take two forms: a template or lambda.

defsc also allows you to specify the query as a template or lambda.

As with :query and :ident, :initial-state supports a template and lambda form.

The template form for initial state is a bit magical, because it tries to sanity check your initial state, but also has to support relations through joins. Finally it tries to eliminate typing for you by auto-wrapping nested relation initializations in get-initial-state for you by deriving the correct class to use from the query. This further reduces the chances of error; however, you may find the terse result more difficult to read and instead choose to write it yourself. Both ways are supported:

Available from Fulcro 2.8+.

The :pre-merge option offers a hook to manipulate data entering your Fulcro app at component level. The option looks like this:

The :pre-merge lambda receives a single map containing the following keys:

and returns the data that should actually be merged into app state. This feature requires an more complete understanding of normalization and full stack operation, and is covered in a later chapter.

Support for using fulcrologic/fulcro-css is built-in. Before 2.4 it was a dynamic dependency so to use needed to include the fulcrologic/fulcro-css library in your project dependencies and require the fulcro-css.css namespace in any file that used this support.

As of version 2.4 it is intregrated with Fulcro, and requires no special dependency.

The keys in the defsc options map to leverage co-located CSS are:

Both are optional. If you use neither, then your code will not incur a dependency on the fulcro-css library.

See Colocated CSS for more details.

It is sometimes useful to be able to run some code once on component construction. In React this is particularly useful when you want a function for saving off :ref or as other callbacks (so the function isn’t changing all the time).

There is no formal constructor for defsc, but you can get exactly the effect of a constructor by placing the code for it in :initLocalState, which is guaranteed to run once and only once per instance construction:

The options of defsc allow for React Lifecycle methods to be defined (as lambdas). The this parameter of defsc is in scope for all of them, but not props or computed. You can obtain computed using prim/get-computed. This is because the lifecycle method may receive prior or next props, and using the top parameter list could be confusing.

The signatures are:

See the React documentation for more details on how these work.

The sanity checking mentioned in the earlier sections causes compile errors. The errors are intended to be self-explanatory. They will catch common mistakes (like forgetting to query for data that you’re pulling out of props, or misspelling a property).

Feel free to edit the components in this source file and try out the sanity checking. For example, try:

In some cases the sanity checking is more aggressive that you might desire. To get around it simply use the lambda style.

It is possible that your logic and state will be much simpler if your UI components derive some values at render time. A prime example of this is the state of a "check all" button. The state of such a button is dependent on other components in the UI, and it is not a separate value. Thus, your UI should compute it and not store it else it could easily become out of sync and lead to more complex logic.

Many reusable components will need to tell their parent about some event. For example, a list item generally wants to tell the parent when the user has clicked on the "remove" button for that item. The item itself cannot be truly composable if it has to know details of the parent. But a parent must always know the details of a child (it rendered it, didn’t it?). As such, manipulations that affect the content of a parent should be communicated to that parent for processing. The mechanism for this is identical to what you’d do in stock React: callbacks from the child.

The one major difference is how you pass the callback to a component.

The query and data feed mechanisms that supply props to a component are capable of refreshing a child without refreshing a parent. This UI optimization can pull the props directly from the database using the query, and re-feed them to the child.

But this mechanism knows nothing about callbacks, because they are not (and should not be) stored in the client database. Such a targeted refresh of a component cannot pass callbacks through the props because the parent is where that is coded, but the parent may not be involved in the refresh!

So, any value (function or otherwise) that is generated on-the-fly by the parent must be passed via fulcro.client.primitives/computed. This tells the data feed system how to reconstruct the complete data should it do a targeted update.

A very common pattern in React is to define a number of custom components that are intended to work in a nested fashion. So, instead of just passing props to a factory, you might also want to pass other React elements. This is fully supported in Fulcro, but can cause confusion when you first try to mix it with the data-driven aspect of the system.

Focus is a stateful browser mechanism, and React cannot force the rendering of "focus". As such, when you need to deal with UI focus it generally involves some interpretation, and possibly component local state. One way of dealing with deciding when to focus is to look at a component’s prior vs. next properties. This can be done in componentDidUpdate. For example, say you have an item that renders as a string, but when clicked turns into an input field. You’d certainly want to focus that, and place the cursor at the end of the existing data (or highlight it all).

If your component had a property called editing? that you made true to indicate it should render as an input instead of just a value, then you could write your focus logic based on the transition of your component’s props from :editing? false to :editing? true.

However, The wrapped inputs of Fulcro 2.3.0 and earlier (which fixed a different issue with React) did not work with the functional ref technique (use strings and dom/node instead). As of 2.3.1 this is fixed, and while inputs still have the internal wrapping to prevent "lost keys" bugs, they work with both the older string support or functional refs.

Libraries like D3 are great for dynamic visualizations, but they need full control of the portion of the DOM that they create and manipulate.

In general this means that your render method should be called once (and only once) to install the base DOM onto which the other library will control.

For example, let’s say we wanted to use D3 to render things. We’d first write a function that would take the real DOM node and the incoming props:

This function should do everything necessary to render the sub-dom (and update it if the props change). Then we’d wrap that under a component that doesn’t allow React to refresh that sub-tree via shouldComponentUpdate.

Below is a demo of this:

The things to note for this example are:

Sometimes you need to use component-local state to avoid the overhead in running a query to feed props. An example of this is when handing mouse interactions like drag. You’ll typically use React refs to grab the actual low-level canvas.

In Fulcro version before 2.6 there are actually two ways to change component-local state. One of them defers rendering to the next animation frame, but it also reconciles the database with the stateful components. This one will not give you as much of a speed boost (though it may be enough, since you’re not changing the database or recording more UI history).

The other mechanism completely avoids this, and just asks React for an immediate forced update.

In Fulcro 2.6 set-state! is a Fulcro wrapper of React’s setState, but it let’s you use cljs maps instead of js ones. The shallow merge described by React is honored as if you used an updater function (there is no need for an updater function). The set-state! also allows a callback to give you full React compatibility. Note, however, that React 16’s setState schedule a state update and render. It is not guaranteed to be immediate.

The update-state! function in Fulcro is like Clojurescripts swap! function, and uses set-state! behind the scenes.

In older versions of Fulcro:

In this example we’re using set-state!, and you can see it is still plenty fast (in 2.6 there is no difference)!

The component receives mouse move events to show a hover box. To make this move in real-time we use component local state. Clicking to set the box, or resize the container are real transactions, and will actually cause a refresh from application state to update the rendering.

Integrating React components is fairly straightforward if you have used React from JS before. The curve comes having spent time with libraries or abstractions like Om and friends. JSX will also abstract some of this away, so it’s not just the cljs wrappers. For a good article explaining some of the concepts read, React Elements The take-aways here are:

It is very important to consider when using any of these functions - the children. JS does not have a built in notion of lazy sequences. Clojurescript does. This can create subtle bugs when evaluating the children of a component.

fulcro.util/force-children helps us in this regard by taking a seq and returning a vector. We can use this to create our own factory function, much like React.createFactory:

This is fine, but you will notice that children in our factory may be missing keys. Because we passed a vector in, React won’t attach the key attribute. We can solve this problem by using the apply function.

Here the apply function will pass the children in as args to React.createElement, thus avoiding the key problem as well as the issue with lazy sequences.

Now that we have some background on creating React Elements it’s pretty simple to implement something. Let' look at making a chart using Victory. We are going to make a simple line chart, with an X axis that contains years, and a Y axis that contains dollar amounts. Really the data is irrelavent, it’s the implementation we care about.

The running code and source are below:

A common pattern in React libraries is to use a function as a single child instead of an actual element. This is an accepted and widely used pattern, but you need to do a simple extra step for it to work properly with Fulcro. You see, Fulcro components use some behind-the-scenes bindings to allow for targeted UI rendering optimizations, and when you embed them in a function that is invoked from external JS out of that context, things won’t work correctly.

For example, the react-motion library gives you React tools that can animate DOM motion. It animates variables that you apply to nested DOM, and it does this through the function-as-a-child pattern. Here’s an example from a demo project (which uses shadow-cljs to get easy access to NPM libraries):

The key is the call to with-parent-context. It causes the enclosed elements to have bindings pulled from the component passed as the first parameter (in this case this). Rendering will work correctly without this wrapper, but interactions (particularly transact!) will not operate correctly without it.

CSS can be co-located on any component. This CSS does not take effect until it is embedded on the page (see Embedding The CSS below). The typical steps for usage are:

A typical file will have the following layout:

In the above example, the upsert results in this CSS on the page:

with a DOM for the UI of:

Garden’s selectors are supported. These include the CSS combinators and the special & selector. Using the $-prefix will also prevent the selectors from being localized.

See Garden’s documentation for more details on more complex rules.

There are two ways of placing the CSS for a (group of) components on a page:

(upsert-css ID {:component Component}) will pull (recursively) the rules of Component, translate them to legal CSS, and then insert them on the body of the page’s DOM at the given ID (overwriting the old style element with that same ID). If you ensure that this upsert happens on hot code reload, then your CSS will update as you edit your code.

Typically, you’ll run upsert-css with your initial mount and in your hot code reload trigger. This means that the computational overhead for the CSS is limited to initial startup.

(style-element {:component Component}) will pull (recursively) the rules for Component and return a React style element. This allows you to embed CSS for a sub-tree of components in an "on-demand" fashion, since the element will only render of the component that uses it renders. The problem with this method is that the computational overhead for computing the CSS is moved into your primary rendering. This, however, is quite convenient in situations like devcards where you’d like to easily ensure that the CSS is there, but don’t want to have to worry about conflicting with existing style elements on the top-level page.

The live demo below upserts the co-located CSS from the code itself, but the embedded rules also base the color on the value in an atom (think theme color). At any time you can change your various embedded data on colocated CSS and re-upsert the generated result!

The upsert-css and style-element functions are conveniences for CLJS DOM, but they do not work in CLJ.

Instead use (garden/css (fulcro-css.css/get-css Component)) to get a string version of the generated CSS and embed that in the page. Version 2.4.1+ includes fulcro-css.css/raw-css for this expression.

You can use the raw string in generated HTML, or use the server-compatible DOM functions:

The new injections namespace also has an improved upsert (client-only DOM node upsert), and a compute-css function the returns the CSS as a string (useful for generating the upserted node in SSR). They take the exact same options map as the style-element.

There is a fulcro.client.localized-dom-server namespace that provides the CLJ versions of the DOM functions. In order to write UI in CLJC files you will need to make sure you use a conditional reader tag to include the correct namespace for the correct langauge:

So what’s the issue with using React HOC in Fulcro Interop: * Fulcro will embed React JS components (ones created by HOC) * React JS HOC will wrap Fulcro components

In the first case React JS components (like these from google-maps-react) expect props to be plain JavaScript objects, not ClojureScript maps. Fulcro components pass ClojureScript to nested components thus props need to be converted. This part is described in Fulcro Book’s chapter on Factory Functions for JS React Components. All we need to do is to have a factory function that will do the conversion. For example:

In the second scenario we will have React JS component passing plain JS object props to our Fulcro component and we need to add a layer that will do JS → Cljs props conversion.

Let’s create our sample Fulcro LocationView component. It queries for view title, location’s lat and lng and google which is the Google Maps API object required by google-maps-react components. It’s managed by google-maps-react HOC wrapper and provided in props passed in our wrapped component.

Now we need to create a factory for our LocationView. It will need to sneak props as Cljs map so it’s available for our wrapped LocationView component:

We also need LocationView factory that will get JS props received from HOC and will recover our Cljs map props enhancing it also with google object provided by HOC. We use "function as child" React pattern.

Now we can finally create a factory for LocationView component that will be used in our client UI code:

Now we can use our LocationView in our views:

utils-hoc namespace presented below provides a reusable hoc-factory that can be used to handle all the boilerplate code and interop gluing. It supports :extra-props-fn in the opts argument that can be used to customize the final props passed to the wrapped component. The code below shows its usage where google value from js-props (injected by google-maps-react HOC wrapper) needs to be propagated under :google entry in Cljs props passed to the wrapped LocationView component.

defui is aware of the following React-centric methods, which you can override:

See React Lifecycle Examples for some specific examples, and the React documentation for a complete description of each of these.

defui supports implementations of protocols in a static context. It basically means that you’d like the methods you’re defining to go on the class (instead of instance), but conform to the given protocol. There is no Java analogue for this, but in Javascript the classes themselves are open.

There are two core protocols for supporting a component’s data in the graph database. They work in tandem to find data in the database for the component, and also to take data (e.g. from a server response or initial state) and normalize it into the database.

Both of these protocols must be declared static. The reason for this is initial normalization and query: The system has to be able to ask components about their ident and query generation in order to turn a tree of data into a normalized database.

Queries must be composed towards the root component (so you end up with a UI query that can pull the entire tree of data for the UI).

Fulcro’s defui is identical in syntax to Om Next’s defui. Porting Om Next UI code to Fulcro is a simple matter of changing namespaces.

The fulcro.client.routing/defsc-router macro (2.6.18+) emits a union component that can be switched to point at any kind of component that it knows about. The support for parameterized routers in the routing tree makes it possible to very easily reuse the UI router as a component that can show one of many screens in the same location.

This is particularly useful when you have a list of items that have varying types, and you’d like to, for example, show the list on one side of the screen and the detail on the other.

To write such a thing one would follow these steps:

The output of the macro:

is roughly this (cleaned up from macro output):

You can see that this just defines a union whose "selection" is controlled by the :current-route property!

Here is a complete working example that uses this to make a UI around displaying things of various types: