{"id":15392685,"url":"https://github.com/jackdbd/fulcro-app","last_synced_at":"2026-04-19T22:05:06.279Z","repository":{"id":45096591,"uuid":"445779818","full_name":"jackdbd/fulcro-app","owner":"jackdbd","description":null,"archived":false,"fork":false,"pushed_at":"2022-01-08T20:28:35.000Z","size":92,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-13T11:43:36.747Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jackdbd.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-08T09:45:06.000Z","updated_at":"2022-01-08T16:24:31.000Z","dependencies_parsed_at":"2022-09-16T13:46:49.180Z","dependency_job_id":null,"html_url":"https://github.com/jackdbd/fulcro-app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jackdbd/fulcro-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Ffulcro-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Ffulcro-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Ffulcro-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Ffulcro-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackdbd","download_url":"https://codeload.github.com/jackdbd/fulcro-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Ffulcro-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32024267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T15:15:40.733Z","updated_at":"2026-04-19T22:05:06.261Z","avatar_url":"https://github.com/jackdbd.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"== The Project\nifdef::env-github[]\n:tip-caption: :bulb:\n:note-caption: :information_source:\n:important-caption: :heavy_exclamation_mark:\n:caution-caption: :fire:\n:warning-caption: :warning:\nendif::[]\n\n== Status\n\nThis is an official template for a Fulcro starter project that might go on to become a production application. It includes a number \nof features that a beginner *will not* need for just playing with the library (full CI test setup, workspaces), but is simple \nenough that a beginner should have no real problem using it.\n\nBeginners should therefore either use this template, or just generate simple play projects from the instructions in\nthe https://book.fulcrologic.com[Developer's Guide].\n\nFulcro also has a Rapid Application Development add-on that makes building a production application faster and easier; \nhowever, a *beginner* should *not* start with RAD except to satisfy surface-level curiosity. RAD requires that you understand\nthe core library (even though most of it uses convention and configuration over actual code). If you understand Fulcro and are\nworking on a real production application then you should probably consider using the setup from the\nhttps://github.com/fulcrologic/fulcro-rad-demo[Fulcro RAD demo] as starting point instead of this template. \n\nRAD gives you a lot of leverage for a new project, and includes a number of pre-written patterns written *in* Fulcro.\nIt includes very good HTML5 routing, form/report support. It *does not limit* your options, just expands what you have available\nby default.\n\n== About This Template\n\nThis template includes a server with a mock database and https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF]\nprotection and a client with login. It also integrates https://github.com/nubank/workspaces/[Nubank Workspaces] for a\nvisual, interactive development environment for Fulcro components, which you can choose to use.\nBoth backend Clojure and frontend ClojureScript REPLs are configured and started. There are also sample frontend tests.\n\nThe server code leverages https://github.com/tolitius/mount[Mount] to make it easy to start and to reload changes - see\nthe helper functions in link:https://github.com/fulcrologic/fulcro-template/blob/master/src/dev/development.clj[`src/dev/development.clj`].\nClient hot code reloading is handled automatically by https://shadow-cljs.org/[shadow-cljs].\n\nThe main project source is in `src/main`, the frontend code in `.cljs` files in `+app.*+` and `+app.ui.*+`.\n\nDependency Aliases:\n\nYou will want to enable the `:dev` dependency while developing this project.  In IntelliJ this is in the\n\"Clojure Deps\" border tab window under \"Aliases\".\n\n== Quick Start\n\nThis is a manual to get started with this example project.\nIt comes with helper `npm run` scripts pre-loaded, you can find them in the package.json file.\n\nTypically 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\n\n```Shell\ngit clone --depth 1 -o fulcro-template https://github.com/fulcrologic/fulcro-template.git fulcro-app\ncd fulcro-app\n\n# The shadow-cljs compiler is a dependency.\nyarn install # or: npm install\n\n# 1. Start shadow-cljs frontend compilation server:\nnpx shadow-cljs server\n# 2.: Visit the shadow-cljs compile server UI at http://localhost:9630\n#     and enable the \"main\" and optionally \"workspaces\" builds\n# 3. Start the backend server:\n#    (Note: for proper development you will want to start it in a nREPL-based\n#     REPL, see the detailed instructions for \"The API Server\" below.)\nclj -A:dev -J-Dtrace -J-Dguardrails.enabled=true\nuser=\u003e (require 'development)\nuser=\u003e (in-ns 'development)\ndevelopment=\u003e (start)\n# after modifications of the backend code run: `(restart)`\n# 4. Visit the application at http://localhost:3000\n\n# (Optional): Visit the Workspaces UI at http://localhost:3000/wslive.html\n# (Optional): Run tests via `npm run client/test` and visit http://localhost:8022\n```\n\n=== The shadow-cljs compile server\n\nYou can find the UI of the frontend compile server here:\nhttp://localhost:9630\nThere you can kick off the compilation of the other targets.\n\n=== Connect to the CLJS nREPL:\n\n1. Open and connect your nREPL to localhost:9000.\n2. Execute `(shadow/repl :main)`. (you can select another target of course)\n\n=== Backend Clojure nREPL:\n\nThe instructions provided above do not start a REPL server for the backend, only a simple\ninteractive REPL session. See the \u003c\u003cthe-api-server,The API Server\u003e\u003e section below to learn\nhow to start the server from a nREPL REPL that you can connect your editor to.\n\n=== Workspaces\n\nIf you choose to use https://github.com/nubank/workspaces[Workspaces], you have two options,\nyou can run them with the actual backend as described in the Quick Start above\nor you can run only the frontend part (communication with the backend will fail due to CSFR):\n`npm run client/workspaces` and visit http://localhost:8023\n\nHave a look at `src/workspaces`.\n\n== Detailed instructions\n\n=== Setting Up\n\nThe shadow-cljs compiler uses all js dependencies through\nNPM. If you use a library that is in cljsjs you will also have to add\nit to your `package.json`.\n\nYou also cannot compile this project until you install the ones it\ndepends on already:\n\n```\n$ npm install\n```\n\nor if you prefer `yarn`:\n\n```\n$ yarn install\n```\n\nAdding NPM Javascript libraries is as simple as adding them to your\n`package.json` file and requiring them! See the\nhttps://shadow-cljs.github.io/docs/UsersGuide.html#_javascript[the Shadow-cljs User's Guide]\nfor more information.\n\n=== Development Mode\n\nShadow-cljs handles the client-side development build. The file\n`src/main/app/client.cljs` contains the code to start and refresh\nthe client for hot code reload.\n\nIn general it is easiest just to run the compiler in server mode:\n\n```\n$ npx shadow-cljs server\nINFO: XNIO version 3.3.8.Final\nNov 10, 2018 8:08:23 PM org.xnio.nio.NioXnio \u003cclinit\u003e\nINFO: XNIO NIO Implementation Version 3.3.8.Final\nshadow-cljs - HTTP server for :test available at http://localhost:8022\nshadow-cljs - HTTP server for :workspaces available at http://localhost:8023\nshadow-cljs - server version: 2.7.2\nshadow-cljs - server running at http://localhost:9630\nshadow-cljs - socket REPL running on port 51936\nshadow-cljs - nREPL server started on port 9000\n...\n```\n\nthen *navigate to the server URL* (shown in this example as http://localhost:9630) and\nuse the *Builds* menu to enable/disable whichever builds you want watched/running.\n\nShadow-cljs will also start a web server for any builds that configure one. This\ntemplate configures one for workspaces (if running without the Clojure backend is enough for you),\nand one for tests:\n\n- Workspaces (without backend): http://localhost:8023\n- Workspaces (with the backend; start it first!): http://localhost:3000/wslive.html\n- Tests: http://localhost:8022\n\nSee the server section below for working on the full-stack app itself.\n\n==== Client REPL\n\nThe shadow-cljs compiler starts an nREPL. It is configured to start on\nport 9000 (in `shadow-cljs.edn`).\n\nIn IntelliJ: add a *remote* Clojure REPL configuration with\nhost `localhost` and port `9000`.\n\nthen:\n\n```\n(shadow/repl :main)\n```\n\nwill connect you to the REPL for a specific build (NOTE: Make sure you have\na browser running the result, or your REPL won't have anything to talk to!)\n\nIf you're using CIDER\nsee https://shadow-cljs.github.io/docs/UsersGuide.html#_cider[the Shadow-cljs User's Guide]\nand the comments in `deps.edn` for more information.\n\n==== The API Server\n\nIn order to work with your main application you'll want to\nstart your own server that can also serve your application's API.\n\nStart a https://cursive-ide.com/userguide/repl.html#local-repls[LOCAL clj nREPL in IntelliJ] (using IntelliJ's classpath with\nthe `dev` https://cursive-ide.com/userguide/deps.html#working-with-aliases[alias selected in the Clojure Deps tab]), or from the command line:\n\n```bash\n$ clj -A:dev -J-Dtrace -J-Dguardrails.enabled=true\nuser=\u003e (require 'development)\ndevelopment=\u003e (in-ns 'development)\ndevelopment=\u003e (start)\ndevelopment=\u003e (stop)\n...\ndevelopment=\u003e (restart) ; stop, reload server code, and go again\ndevelopment=\u003e (tools-ns/refresh) ; retry code reload if hot server reload fails\n```\n\nThe `-J-Dtrace` adds a JVM argument that will enable performance tracing for Fulcro Inspect's network tab so you can\nsee how your resolvers and mutations are performing.\n\nThe `-J-Dguardrails.enabled=true` turns on guardrails instrumentation of guardrails spec'd functions, which is a wrapper\nof Clojure spec that makes instrumentation and production-time elision (for performance and size) much easier.\n\nNOTE: For real development, please use an editor that has REPL integration, like Cursive (recommended) or\nSpacemacs.\n\nThe URL to work on your application is then\nhttp://localhost:3000.\n\nHot code reload, preloads, and such are all coded into the javascript.\n\n==== Preloads\n\nThere is a preload file that is used on the development build of the\napplication `app.development-preload`. You can add code here that\nyou want to execute before the application initializes in development\nmode.\n\n==== Fulcro Inspect\n\nFulcro inspect will preload on the development build of the main\napplication and workspaces.  You must install the plugin in Chrome from the\nChrome store (free) to access it.  It will add a Fulcro Inspect tab to the\ndeveloper tools pane.\n\n== Tests\n\nTests are in `src/test`. Any test namespace ending in `-test` will be auto-detected.\n\n```\nsrc/test\n└── app\n    └── sample_test.cljc          spec runnable by client and server.\n```\n\nYou can write plain `deftest` in here, and it is preconfigured to support the helper macros in `fulcro-spec` as well.\n\n=== Running tests:\n\n\n==== Clojure Tests\n\nTypically you'll just run your tests using the editor of choice (e.g. Run tests in namspace in IntelliJ).\n\nThe tests are also set up to run with Kaocha at the command line for your convenience and CI tools:\n\n```\n$ clj -A:dev:clj-tests --watch\n```\n\nSee the https://github.com/lambdaisland/kaocha[Kaocha project] for more details.\n\n==== Clojurescript tests\n\nThe tests can be run in any number of browsers simply by navigating to the test URL that shadow-cljs outputs.\n\nCI support is done through the `ci-test` build in shadow, and via Karma.\n\nIf you start the `ci-tests` build in Shadow-cljs, then you can also run cljs tests in a terminal \"watch mode\"\nwith:\n\n```\nnpx karma start\n```\n\nOf course, this make CLJS CI easy:\n\n```\nnpx shadow-cljs compile ci-tests\nnpx karma start --single-run\n```\n\n==== Running all Tests Once\n\nThere is a UNIX Makefile that includes all of the CI commands as the default target. Just run:\n\n```\nmake\n```\n\n== Workspaces\n\nWorkspaces is a project by Nubank that is written in Fulcro, and has great support for developing in\nFulcro. It is similar to devcards but has a more powerful user interface, integration with Fulcro Inspect,\nand much more.\n\nThe source directory for making additions to your workspace is `src/workspaces`.\n\nIMPORTANT: Any namespace ending in `-ws` will be auto-detected and added to your workspace!\n\n== Standalone Runnable Jar (Production, with advanced optimized client js)\n\nSee tools deps projects like Depstar. You'll need to make a release js build, optionally\npre-compile your CLJ, and package it.  We will likely add a demo of this process soon.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackdbd%2Ffulcro-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackdbd%2Ffulcro-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackdbd%2Ffulcro-app/lists"}