Home

Awesome

portal

A clojure tool to navigate through your data.

cljdoc Clojars Project VS Code Extension Version Get help on Slack

<a target="_blank" href="https://djblue.github.io/portal/?content-type=application/edn&content-url=https://raw.githubusercontent.com/djblue/portal/gh-pages/docs.edn"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/1986211/196015562-238cf450-6467-451c-a985-04c7a9b49dba.png"> <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/1986211/196015567-74ba9153-341a-4fd7-be47-2c26f0c88c2e.png"> <img src="https://user-images.githubusercontent.com/1986211/196015562-238cf450-6467-451c-a985-04c7a9b49dba.png"> </picture> </a>

The portal UI can be used to inspect values of various shapes and sizes. The UX will probably evolve over time and user feedback is welcome!

For an in-depth explanation of the UI, you can jump to the UI docs.

Demo

To get an overview of the Portal UI and workflow, checkout the following recording of a live demo I gave for London Clojurians.

<a target="_blank" href="https://www.youtube.com/watch?v=Tj-iyDo3bq0"> <img src="https://img.youtube.com/vi/Tj-iyDo3bq0/hqdefault.jpg" alt="London Clojurians Demo" /> </a>

More video presentations on Portal can be found here.

Usage

To start a repl with portal, run the clojure >= 1.10.0 cli with:

clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}}}'

or for a web clojurescript >= 1.10.773 repl, do:

clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}
                    org.clojure/clojurescript {:mvn/version "1.10.844"}}}' \
    -m cljs.main

or for a node clojurescript >= 1.10.773 repl, do:

clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}
                    org.clojure/clojurescript {:mvn/version "1.10.844"}}}' \
    -m cljs.main -re node

or for a babashka >=0.2.4 repl, do:

bb -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}}}'

or for a lein project.clj, add:

{:profiles {:dev {:dependencies [[djblue/portal "0.58.2"]]}}}

or as a global profile, add to ~/.lein/profiles.clj:

{:portal {:dependencies [[djblue/portal "0.58.2"]]}}

[!NOTE] If you add Portal to a profile other than :dev, when starting a REPL start it with with-profiles +portal. The + is important.

or for Clojure CLR, checkout this example project,

or for examples on how to integrate portal into an existing project, look through the examples directory.

[!NOTE] Portal can also be used without a runtime via the standalone version.

API

Try the portal api with the following commands:

;; for node and jvm
(require '[portal.api :as p])

;; for web
;; NOTE: you might need to enable popups for the portal ui to work in the
;; browser.
(require '[portal.web :as p])


(def p (p/open)) ; Open a new inspector

;; or with an extension installed, do:
(def p (p/open {:launcher :vs-code}))  ; jvm / node only
(def p (p/open {:launcher :intellij})) ; jvm / node only

(add-tap #'p/submit) ; Add portal as a tap> target

(tap> :hello) ; Start tapping out values

(p/clear) ; Clear all values

(tap> :world) ; Tap out more values

(prn @p) ; bring selected value back into repl

(remove-tap #'p/submit) ; Remove portal from tap> targetset

(p/close) ; Close the inspector when done

(p/docs) ; View docs locally via Portal - jvm / node only

[!WARNING] Portal will keep objects from being garbage collected until they are cleared from the UI.

Options

Options for portal.api/open:

OptionDescriptionDefaultSpec
:window-titleCustom window title for UI"portal"string?
:themeDefault theme for UI:portal.colors/nord
:valueRoot value of UI(atom (list))
:appLaunch UI in Chrome app windowtrueboolean?
:launcherLaunch UI using this editor#{:vs-code :intellij :emacs}
:editorEnable editor commands, but use separate UI#{:vs-code :intellij :emacs}
:portHttp server port for UI0int?
:hostHttp server host for UI"localhost"string?

For more documentation, take a look through the docs.