The Project

Note	This template is in progress. It should be working, but is intended to have a lot more features.

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

The main project source is in src/main.

Setting Up

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:

$ npm install

or if you prefer yarn:

$ 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](https://shadow-cljs.github.io/docs/UsersGuide.html#_javascript) for more information.

Development Mode

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, and one for tests:

• Workspaces: [http://localhost:8023/workspaces](http://localhost:8023/workspaces)

• Tests: [http://localhost:8022](http://localhost:8022)

See the server section below for working on the full-stack app itself.

Client REPL

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](https://shadow-cljs.github.io/docs/UsersGuide.html#_cider) and the comments in deps.edn for more information.

The API Server

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-Dghostwheel.enabled=true
user=> (start)
user=> (stop)
...
user=> (restart) ; stop, reload server code, and go again
user=> (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-Dghostwheel.enabled=true turns on ghostwheel instrumentation of ghostwheel spec’d functions, which is a wrapper of Clojure spec that makes instrumentation and production-time elision (for performance and size) much easier.

Note	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](http://localhost:3000).

Hot code reload, preloads, and such are all coded into the javascript.

Preloads

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.

Fulcro Inspect

Fulcro inspect will preload on the development build of the main application and workspaces. You must install the plugin in Chrome from the Chrome store (free) to access it. It will add a Fulcro Inspect tab to the developer tools pane.

Cordova

The cordova android target can be used to build android, electron or ios apps from the prebuild sources.

Currently only the android and ios target is integrated into this build.

iOS steps

Install the XCode IDE with your App Store

Install homebrew following the guidelines at the website https://www.wdiaz.org/installing-applications-on-mac-like-linux-with-homebrew/

$>/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install the Node Version Manager nvm using homebrew

$>brew install nvm

add nvm to your .bashrc or .zshrc

export NVM_DIR="$HOME/.nvm"
NVM_HOMEBREW="/usr/local/opt/nvm/nvm.sh"
[ -s "$NVM_HOMEBREW" ] && \. "$NVM_HOMEBREW"

install stable Node version

$>nvm install node
$>nvm use node

More infos: https://www.wdiaz.org/how-to-install-nvm-with-homebrew/

In case cordova complains, building ios-deploy tool chain, try to change the devtool-path using xcode-select and sudo.

Select the right xcode-devtools using xcode-select:

$>sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Install Cordova:

$> npm install -g cordova

Installing clojure:

$> brew install clojure

For further information see https://gist.github.com/rakhmad/2407109

Permission problems: If there are permission promblems concerning adoptopenjdk-13.jdk go to System Settings → Security → General → Lock Symbol Click on the Lock symbol and enter your password if requested, then you are able to allow the adoptopenjdk-13 application to run.

The following run command, will build an app for iOS:

$> yarn run  cordova/ios-all

This will invoke the following targets:

1. cordova/build-main-dev → transpile clojurescript code with shadow-cljs

2. cordova/build-assets → resize icon and splashscreen to a wide range of devices

3. cordova/prepare-dev → copy necessary css and static resources via WebPack to cordova directory

4. cordova/prepare-ios → add ios platform to cordova (to be save)

5. cordova/build-ios → start the cordova build process

To test the app, connect a device or start an emulator using the AVD-manager and hit

$> yarn run  cordova/install-ios

You should now have a running app on your phone or emulator

For further information about how to sign, publish or debug an iOS app consider the following manuals

https://cordova.apache.org/docs/en/9.x/guide/platforms/ios/plugin.html

Remote debug the Web-View fulcro app in Safari:

https://appletoolbox.com/use-web-inspector-debug-mobile-safari/ https://blog.idrsolutions.com/2015/02/remote-debugging-ios-safari-on-os-x-windows-and-linux/

TODO: connect the fulcro inspect to the ios-client repl

android steps

The following run command, will build a dev APK for android:

$> yarn run  cordova/android-all

This will invoke the following targets:

1. cordova/build-main-dev → transpile clojurescript code with shadow-cljs

2. cordova/build-assets → resize icon and splashscreen to a wide range of devices

3. cordova/prepare-dev → copy necessary css and static resources via WebPack to cordova directory

4. cordova/prepare-android → add android platform to cordova (to be save)

5. cordova/build-android → start the cordova build process

To test the app, connect a device or start an emulator using the AVD-manager and hit

$> yarn run  cordova/install-android

You should now have a running app on your phone or emulator

For web-debugging you can use a chromium or chrome-browser and surf to chrome://inspect#devices.

Once the app appears you can click on inspect to get a developer console.

cordova plugins

Several plugins are beeing used in order to enable functionality like background location tracking and open with/share with features

For reference the plugin add commands are listed here:

$> cordova plugin add cc.fovea.cordova.openwith --variable ANDROID_MIME_TYPE="application/gpx+xml"  --variable IOS_URL_SCHEME=mapitm --variable IOS_UNIFORM_TYPE_IDENTIFIER=public.xml

Tests

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.

Running tests:

Clojure Tests

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.

Clojurescript tests

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

Running all Tests Once

There is a UNIX Makefile that includes all of the CI commands as the default target. Just run:

make

Workspaces

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.

Important

Any namespace ending in -ws will be auto-detected and added to your workspace!

Standalone Runnable Jar (Production, with advanced optimized client js)

See tools deps projects like Depstar. You’ll need to make a release js build, optionally pre-compile your CLJ, and package it. We will likely add a demo of this process soon.