Installation — employeerepublic/yada-core 1.2.16

Installation

yada is a Clojure library and if you are using it directly from a Clojure application with a Leiningen project.clj file, include the following in the file’s :dependencies section.

[yada "1.2.16"]
[aleph "0.4.1"]
[bidi "2.0.12"]

Setting up a development environment

The best way to learn is to experiment with yada, either on its own or by using it to build some service you have in mind. Either way you’ll want to set up a quick development environment.

The Easy Way: Clone edge

The quickest and perhaps easiest way to get started is to clone the yada branch of JUXT’s edge repository. This is a continuously improving development environment representing our firm’s best advice for building Clojure projects.

$ git clone git@github.com/juxt/edge

edge is opinionated and combines a number of practices that we’ve found useful on many projects at JUXT.

If you’re new to Clojure, we recommend learning yada with edge. Not only is it packed full of examples for you to explore, the project can provide a solid foundation for your own projects with an architecture that is proven to scale as your project grows.

The Simple Way: Construct your own

If you prefer to build your own development environment you’ll need a few pointers in order to integrate with yada.

Serving resources

To serve the resources you define with yada you’ll need to choose a port and start a web server. Currently, yada provides its own built-in web server (Aleph), but in the future other web servers will be supported. (For now, please be reassured that Aleph will support many thousands of concurrent connections. Aleph is built on Netty, a very capable platform used by Google, Apple, Facebook and many others to support extreme workloads.)

To start a web-server, just require listener from yada.yada and call it with a route structure and some configuration that includes the port number.

(require '[yada.yada :refer [listener resource as-resource]])

(def svr
  (listener
   ["/"
    [
     ["hello" (as-resource "Hello World!")]
     ["test" (resource {:produces "text/plain"
                        :response "This is a test!"})]
     [true (as-resource nil)]]]
   {:port 3000}))

The listener function returns a map. To shutdown the listener, call the 0-arity function contained in the :close entry.

((:close svr))

Creating resources

Resources can be created in the following ways:

From a resource model, calling resource with a map argument
Using as-resource on an existing type known to yada
A normal Ring handler

Routing to resources

A handler can be created from a resource by yada's handler function, and this handler can be used anywhere a Ring-compatible function is expected. This way, you can use any routing library you wish, including Compojure.

However, yada and bidi are designed to work together, and there are a number of features that are enabled when they are used together. That’s why you can put yada resources in a bidi route structure without turning them into handlers, since bidi knows how to do that already.

REPL and Testing

The response-for function is great for testing the Ring response that would be returned from a yada type or handler.

(require '[yada.yada :refer [response-for]])

(response-for "Hello World!")