Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/holyjak/minimalist-fulcro-template-backendless

A minimal template for browser-only Fulcro apps for learning
https://github.com/holyjak/minimalist-fulcro-template-backendless

Last synced: about 2 months ago
JSON representation

A minimal template for browser-only Fulcro apps for learning

Awesome Lists containing this project

README 

        
# minimalist-fulcro-template-backendless



A template for starting a new, frontend-only Fulcro application with in-browser Pathom. Intended for playing with and learning Fulcro, not for production apps, and therefore simpler than the official [fulcro-template](https://github.com/fulcrologic/fulcro-template). It is a good starting point for your learning projects that is hopefully simple enough for you to understand.



For a template that has an actual backend, see [minimalist-fulcro-template](https://github.com/holyjak/minimalist-fulcro-template).



## Note on Pathom 2



Until 2023-09 (last sha 624d546e7), we used Pathom 2.



## Note on alternatives for Pathom 3 and Fulcro Inspect's Index Explorer



Fulcro Inspect's Index Explorer is not compatible with Pathom 3. You need to use a standalone Pathom Viz ([see my article for details](https://blog.jakubholy.net/2023/pathom-viz-for-fulcro-pathom3/).). What you need to do then is to 



1. [download Pathom Viz app](https://github.com/wilkerlucio/pathom-viz/releases)

2. Make `com.example.pathom/enable-pathom-viz` true

3. Reload your app and connect P. Viz to it



P. Viz support is off by default because otherwise it [logs tons of errors](https://clojurians.slack.com/archives/C87NB2CFN/p1696016550457039) and warnings, until you connect it.



## Creating a new application from the template



[Download](https://github.com/holyjak/minimalist-fulcro-template-backendless/archive/refs/heads/main.zip) or clone this repository to your computer and start hacking away.



## Explanation



You will run shadow-cljs, which will watch, compile, and update the sources and also run a HTTP server to serve the application.



## Usage



### Alternative 1: run locally



Prerequisites: [same as shadow-cljs'](https://github.com/thheller/shadow-cljs#requirements).



First, install frontend dependencies via npm, yarn, or similar:



    npm install # or yarn install # reportedly yarn < v3



then start the application either via



    npx shadow-cljs watch main



or, if you have [Babashka](https://babashka.org/) installed, via



    bb run



NOTE: For Calva, do instead start the REPL from the editor - [run Jack-in](https://calva.io/connect/#jack-in-let-calva-start-the-repl-for-you), selecting _shadow-cljs_ then the `:main` build. Remember to load the page in the browser, see below.



Finally, navigate to http://localhost:8000 and, _after that_, connect to the shadow-cljs nREPL at port 9001\* and switch to the browser REPL by evaluating `(shadow/repl :main)` (Calva does the latter for you).



### Alternative 2: Run with VS Code Dev Containers



If you opened the cloned repo in VS Code, it will offer you to open it using Dev Containers,

i.e. inside a pre-configured Docker instance (provided that you have Docker installed).

This may be a great option if you run into problems that could be caused by the environment.



It will take a while (to build the container for the first time). Eventially, a _Terminal_ should open, telling you that everything is fine and to press any key. After you do that, a normal terminal will open, where you should execute shadow-cljs:



```

vscode ➜ /workspaces/minimalist-fulcro-template-backendless (main) $ npx shadow-cljs watch main

```



(Or you could just run Calva Jack-in and select shadow-cljs and the :main build.)



Eventually, Code will inform you that "Your application running on port 8000 is available.", which you can agree to. (Ignore the previous message about 9001, that is nrepl). Then wait for the terminal to show `[:main] Build completed.` and reload the web page. You should be now able to _Calva: Connect to a Running REPL Server in the Project_. When asked, select `shadow-cljs` as the kind of the repl and then the `:main` build.



### Create a standalone build



You can also compile the sources into a directory via



    npx shadow-cljs release main

    # or: bb build



and then serve the whole website using a HTTP server, e.g.:



    cd resources/public/

    python3 -m http.server 8000



## Why is this not suitable for production?



No thought was given to security, performance, monitoring, error tracking and other important production concerns. It also bakes in fulcro-troubleshooting, which you do not want unnecessarily increasing your bundle size in production settings. So if you want to use the template as a starting point for a production application, you will need to add those yourself.



## TODO



* Can we display an error in the UI when we remove the `i-fail` resolver from Pathom? Currently it returns `::p/errors ::p/not-found`, which Fulcro ignores



## License



Copyleft © 2021 Jakub Holý



Distributed under the [Unlicense](https://unlicense.org/).