Server side error handling. Get tracebacks from live sites emailed to you.
4 |(install-traceback-handler email-address & [build-id])Handle any unhandledRejections or uncaughtExceptions that occur outside request handlers. * If email-address is set, errors will be sent to the supplied address. * If build-id is set, it will be added to the log.
Errors are also written to the rotated file logs/error.log and stderr.
You can get a build-id using git rev-parse HEAD | cut -b -8 > build-id.txt and including it with (rc/inline).
Functions to ensuring live-reloading works during development mode.
4 |(nbb-reloader file callback)Sets up filewatcher for development. Automatically re-evaluates this file on changes. Uses browser-sync to push changes to the browser. file can be a path (string) or a vec of strings.
(sync-browser host port & [files])Sets up browser-sync for development. Hot-loads CSS and automatically refreshes on server code change.
6 |Various utilities for server side ClojureScript.
4 |(env k & [default])Returns the environment variable named in k with optional default value.
6 |(env-required k & [msg])Returns the environment variable named in k or exits the process if missing. The message printed on exit can be customised in msg.
7 |(error-to-json err)Convert a JavaScript error into a form that can be returned as JSON data.
8 |My message.
Functions to help with writing log files.
4 |(bind-console-to-file)This is deprecated in favour of tracebacks/install-traceback-handler. Rebinds console.log and console.error so that they write to ./logs/error.log as well as stdout.
(flush-bound-console cb)This is deprecated in favour of tracebacks/install-traceback-handler.
Functions for sending email from web services using node-mailer.
4 |(send-email to from subject & {:keys [transport headers text html]})Send an email.
5 |Uses the SMTP_SERVER environment variable to configure the server to use for sending. For example: SMTP_SERVER=smtps://username:password@mail.someserver.com/?pool=true
If you don’t specify a server ethereal.email will be used and the viewing link will be returned in the url property of the result. You can use this for testing your emails in dev mode.
to and from are valid email addresses.to can be an array of valid email addresses for multiple recipients.subject is the text of the subject line.:text for the body of the email in text format.:html for the body of the email in html format.:smtp-transport keyword argument if you want to re-use the transport to send multiple emails.:headers to pass a map of additional headers.(smtp-transport)Create the SMTP mail transport to be used by send-email.
The SMTP_SERVER environment variable specifies the connection settings. If unset a test account at ethereal.email will be used.
Lightweight database access. The environment variable DATABASE_URL configures which database to connect to.
By default it is set to use a local sqlite database: sqlite://./database.sqlite
DATABASE_URL for Postgres: postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]
(client)The database client that is connected to DATABASE_URL. This allows you to make raw queries against the database.
(ensure-local-postgres-db-exists & [db-url])If DATABASE_URL is for a postgres url then create it if it does not already exist. An example of an on-disk db URL: ‘postgres://%2Fvar%2Frun%2Fpostgresql/DBNAME’.
8 |(f kv-ns filter-function & [pre db])Filter all key-value entries matching a particular namespace and prefix, through the supplied
9 |(kv kv-ns)Access a database backed key-value store (Keyv instance). kv-ns is a namespace (i.e. table). The database to use can be configured with the DATABASE_URL environment variable. See the Keyv documentation for details. The promise based API has methods like (.set kv ...) and (.get kv ...) which do what you’d expect.
(ls kv-ns & [pre db filter-function])List all key-value entries matching a particular namespace and prefix. Returns a promise that resolves to rows of JSON objects containing the values.
11 |kv-ns is the namespace/table name.pre substring to filter key by i.e. keys matching kv-ns:pre....db an database handle (defaults to the one defined in DATABASE_URL).filter-function filter every value through this function, removing falsy results.(perform-select c select-statement deserialize kv-ns pre page-size page filter-function results)Functions for wrangling HTML and rendering Reagent components into selectors.
4 |($ element selector)Shorthand for CSS style querySelector on parsed HTML element such as the document returned by the parse function or a sub-element.
($$ element selector)Shorthand for CSS style querySelectorAll on parsed HTML element such as the document returned by the parse function or a sub-element.
(direct-to-template res template & selector-component-pairs)Render selector component Reagent pairs into the HTML template string and use the express res to send the resulting HTML to the client.
(parse html-string)Shorthand for node-html-parser’s parse function. Returns a dom-like document object (HTMLElement) that can be manipulated as in the browser.
(render-anything source & args)Render anything to HTML. If source is a Reagent form, render-to-static-markup is used. If source is a jsdom HTMLElement or other type of object .toString is used. If source is a fn it will be called with any args that were passed. If source is already a string it is passed through with no change.
(render-into html-string selector reagent-forms)Render a Reagent component into the chosen element of an HTML document.
11 |html-string is the HTML document to be modified.selector is a CSS-style selector such as #app or main.reagent-forms is a valid Reagent component.(select-apply template & selector-application-pairs)Parse template if it is a string and then run each of selector-applications on it. If it is already a document-like object it won’t be parsed first. The selector-applications should each be an array like: [selector document-method-name ...arguments]. For each one the selector will be run and then the method run on the result, with arguments passed to the method. The special ‘method’ setHTML expects a Reagent form which will be rendered and innerHTML will be set to the result.
Utility functions that can be used in client-side code.
4 |(csrf-token)Returns the CSRF token passed by Sitefox in the XSRF-TOKEN cookie. Pass this value when doing POST requests via ajax:
(js/fetch "/api/endpoint"
6 | #js {:method "POST"
7 | :headers #js {:Content-Type "application/json"
8 | :XSRF-Token (csrf-token)}
9 | :body (js/JSON.stringify (clj->js data))})
10 | Note: passing the token via client side cookie is now deprecated. If you want to re-enable it set the client side environment variable SEND_CSRF_COOKIE, and then this function will work again.
See the README for more details: https://github.com/chr15m/sitefox/#csrf-protection
13 |(fetch-csrf-token)Returns a promise which resolves to a string containing the CSRF token fetched from the Sitefox backend server. Pass this value as the X-XSRF-TOKEN when doing POST requests via ajax fetch:
14 | (-> (fetch-csrf-token)
15 | (.then (fn [token]
16 | (js/fetch "/api/endpoint"
17 | #js {:method "POST"
18 | :headers #js {:Content-Type "application/json"
19 | :X-XSRF-TOKEN token} ; <- use token here
20 | :body (js/JSON.stringify (clj->js some-data))}))))
21 | (get-cookie cookie-name & [cookies])Returns the value of the named cookie from js/document.cookies (or optionally the cookies argument).
(json-post url data & [options])Use HTTP post to send data to /url in JSON format. Will convert clj to js datastructures. Will obtain and use a CSRF token. Use options to override the options passed to js/fetch. The options will be shallow-merged into the defaults.
(simple-date-time dt)Returns a simple string representation of the date and time in YYYY-MM-DD HH:MM:SS format.
25 |(time-since date-string & [from-date-string])Returns a string describing how long ago the date described in date-string was.
Functions to start the webserver and create routes.
4 |(add-default-middleware app & [session-options])Set up default express middleware for:
5 |logs/access.log.Pass the session-options map to configure the express-sessions package. Sitefox defaults will be shallow-merged with the options map passed in.
(build-absolute-uri req path)Creates an absolute URL including host and port. Use inside a route: (build-absolute-uri req "/somewhere")
(get-named-route req route-name)Retrieve a route that has previously been named.
14 |(name-route app route route-name)Attach a name to a route that can be recalled with get-named-route.
(reset-routes app)Remove all routes in the current app and re-add the default middleware. Useful for hot-reloading code.
17 |(serve app)Start serving an express app.
18 |Configure BIND_ADDRESS and PORT with environment variables. They default to 127.0.0.1:8000.
(setup-error-handler app template selector view-component & [error-handler-fn])Sets up an express route to handle 404 and 500 errors. This must be the last handler in your server:
20 |(defn setup-routes [app]
21 | (web/reset-routes app)
22 | ; ... other routes
23 | ; 404 and 500 error handling
24 | (web/setup-error-handler app template "main" component-error-page email-error-callback))
25 | Pass it the express app, an HTML string template, query selector and a Reagent view-component. Optionally pass error-handler-fn which will be called on every 500 error with args req, error. The error view-component will be rendered and inserted into the template at selector.
The error component will receive three arguments: * req - the express request object. * error-code - the exact error code that occurred (e.g. 404, 500 etc.). * error - the error object that was propagated (if any).
Example:
29 |(make-error-handler app my-template "main" my-error-component)
To have all 500 errors emailed to you and logged use tracebacks/install-traceback-handler and pass it as error-handler-fn.
(start)Create a new express app and start serving it. Runs (create) and then (serve) on the result. Returns a promise which resolves with app host port server once the server is running.
32 |(static-folder app route dir)Express middleware to statically serve a dir on a route relative to working dir.
(strip-slash-redirect req res n)Express middleware to strip slashes from the end of any URL by redirecting to the non-slash version. Use: `(.use app strip-slash-redirect)
34 |