git.fiddlerwoaroof.com
name mode size
..
cards 040000
dev 040000
main 040000
test 040000
README.html
<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>README.html</title> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/> </head> <body> <h1>The Project</h1> <p>The main project source is in <code>src/main</code>.</p> <p><code> . ├── Makefile ; i18n extract/generate and CI test running ├── karma.conf.js ; CI Runner config ├── package.json ; NPM modules ├── project.clj ; Leiningen project file ├── resources | ├── i18n ; directory for i18n extract/translate/serve | │   ├── es.po ; spanish translations | │   └── messages.pot ; extracted strings (template) |   └── public │   ├── cards.html ; page for mounting dev cards │   ├── index.html ; main app index page │   └── js │   └── test │   └── index.html ; custom test page for running tests in dev mode ├── shadow-cljs.edn ; Shadow-cljs configuration file. CLJS builds. └── src ├── cards │   └── fulcro_cljdoc │   ├── cards.cljs ; Main for devcards │   └── intro.cljs ; A sample devcards file ├── dev │   └── user.clj ; Functions for running web server in development mode ├── main │   ├── config ; configuration files for web server │   │   ├── defaults.edn │   │   ├── dev.edn │   │   └── prod.edn │   └── fulcro_cljdoc │      ├── api │      │   ├── mutations.clj ; server-side implementation of mutations │      │   ├── mutations.cljs ; client-side implementation of mutations │      │   └── read.clj ; server-side reads │      ├── client.cljs ; file that creates the Fulcro client │      ├── development-preload.cljs ; code to run in development mode before anything else │      ├── server.clj ; file that creates the web server │      ├── server_main.clj ; production server entry point │      └── ui │      ├── components.cljc ; Sample reusable component │      └── root.cljc ; Main UI └── test └── fulcro_cljdoc ├── client_test_main.cljs ; setup for dev mode tests └── sample_spec.cljc ; a sample spec in fulcro-spec </code></p> <h2>Setting Up</h2> <p>The shadow-cljs compiler uses all cljsjs and NPM js dependencies through NPM. If you use a library that is in cljsjs you will also have to add it to your <code>package.json</code>.</p> <p>You also cannot compile this project until you install the ones it depends on already:</p> <p><code> $ npm install </code></p> <p>or if you prefer <code>yarn</code>:</p> <p><code> $ yarn install </code></p> <p>Adding NPM Javascript libraries is as simple as adding them to your <code>package.json</code> file and requiring them! See the <a href="https://shadow-cljs.github.io/docs/UsersGuide.html#_javascript">the Shadow-cljs User's Guide</a> for more information.</p> <h2>Development Mode</h2> <p>Shadow-cljs handles the client-side development build. The file <code>src/main/fulcro_cljdoc/client.cljs</code> contains the code to start and refresh the client for hot code reload.</p> <p>Running all client development builds:</p> <p><code> $ npx shadow-cljs watch main cards test ... shadow-cljs - HTTP server for ":main" available at http://localhost:8020 shadow-cljs - HTTP server for ":test" available at http://localhost:8022 shadow-cljs - HTTP server for ":cards" available at http://localhost:8023 ... </code></p> <p>The compiler will detect which builds are affected by a change and will minimize incremental build time.</p> <p>NOTE: The server wil start a web server for all three builds (on different ports). You typically do not need the one for main because you'll be running your own server, but it is there in case you are only going to be writing a client-side app that has no server API.</p> <p>The URLs for working with cards and tests are:</p> <ul> <li>Cards: <a href="http://localhost:8023/cards.html">http://localhost:8023/cards.html</a></li> <li>Tests: <a href="http://localhost:8022/index.html">http://localhost:8022/index.html</a></li> <li>Main: <a href="http://localhost:8020/index.html">http://localhost:8020/index.html</a> (NO API SERVER)</li> </ul> <p>See the server section below for working on the full-stack app itself.</p> <h3>Client REPL</h3> <p>The shadow-cljs compiler starts an nREPL. It is configured to start on port 9000 (in <code>shadow-cljs.edn</code>).</p> <p>In IntelliJ, simply add a <em>remote</em> Clojure REPL configuration with host <code>localhost</code> and port <code>9000</code>.</p> <p>If you're using CIDER see <a href="https://shadow-cljs.github.io/docs/UsersGuide.html#_cider">the Shadow-cljs User's Guide</a> for more information.</p> <h3>The API Server</h3> <p>The shadow-cljs compiler starts a server for serving development files, but you usually will not use it. Instead you'll start your own server that can also serve your application's API.</p> <p>Start a clj REPL in IntelliJ, or from the command line:</p> <p><code>bash $ lein repl user=&gt; (go) ... user=&gt; (restart) ; stop, reload server code, and go again user=&gt; (tools-ns/refresh) ; retry code reload if hot server reload fails </code></p> <p>The URL to work on your application is then <a href="http://localhost:3000">http://localhost:3000</a>.</p> <p>Hot code reload, preloads, and such are all coded into the javascript, so serving the files from the alternate server is fine.</p> <h3>Preloads</h3> <p>There is a preload file that is used on the development build of the application <code>fulcro-cljdoc.development-preload</code>. You can add code here that you want to execute before the application initializes in development mode.</p> <h3>Fulcro Inspect</h3> <p>The Fulcro inspect will preload on the development build of the main application and cards. You can activate it by pressing CTRL-F while in the application. If you need a different keyboard shortcut (e.g. for Windows) see the docs on github.</p> <h2>Tests</h2> <p>Tests are in <code>src/test</code></p> <p><code> src/test └── fulcro_cljdoc ├── client_test_main.cljs entry point for dev-mode client tests └── sample_spec.cljs spec runnable by client and server. </code></p> <h3>Server tests:</h3> <p>Interacting with tests resuts via a browser (also allows test focusing, etc):</p> <p>From a CLJ REPL:</p> <p><code> user=&gt; (start-server-tests) ; start a server on port 8888 showing the server tests </code></p> <p>then navigate to <a href="http://localhost:8888/fulcro-spec-server-tests.html">http://localhost:8888/fulcro-spec-server-tests.html</a></p> <p>If you'd instead like to see them pop up over and over again in a terminal:</p> <p><code> lein test-refresh </code></p> <h3>CI Tests</h3> <p>Use the Makefile target <code>tests</code>:</p> <p><code> make test </code></p> <p>You must have <code>npm</code> and Chrome installed. The tests use the <code>npm</code> utility Karma for actually running the tests. This target will run both client and server tests.</p> <h2>Dev Cards</h2> <p>The source is in <code>src/cards</code>. Remember to add devcard files here, and add a require the for new card namespace to the <code>cards.cljs</code> file.</p> <h2>I18N</h2> <p>The i18n process is codified into a Makefile. The target extracts strings from the source (which must build the js, and run xgettext on it, which you must have installed, perhaps from brew):</p> <p><code> make i18n-extract </code></p> <p>and gives you instructions on generating translations.</p> <p>The translations (po files) are then places into <code>resources/i18n</code> and will be automatically served to the client when the client changes to that locale.</p> <p>See the Developer's Guide for more details.</p> <h2>Standalone Runnable Jar (Production, with advanced optimized client js)</h2> <p><code> lein uberjar java -jar target/fulcro_cljdoc.jar </code></p> </body> </html>