33,59 €
Mehr erfahren.
- Herausgeber: Packt Publishing
- Sprache: Englisch
Master the art of agile single page web application development with ClojureScript
About This Book
- Set up interactive development workflows for the browser or Node.js thanks to the ClojureScript ecosystem
- Learn the basics of interactive single page web app development taking advantage of the functional nature of ClojureScript
- Delve into advanced rich web application development concepts such as Om, along with core.async, using zippers and logic programming, and preparing code for production with testing or optimizing via the Google Closure Compiler
Who This Book Is For
This book is for web application developers who want to benefit from the power of ClojureScript to get an agile and highly productive development platform that targets mainly browser JavaScript.
You are not required to be fluent in Clojure, but it will be easier for you if you have a basic understanding of browser and server-side JavaScript.
What You Will Learn
- Understand how the ClojureScript compiler operates
- Set up interactive development workflows for ClojureScript
- Grasp the basics of the ClojureScript language, including basic syntax, data structures, variable scoping, namespaces, and finally the powerful sequence abstraction
- Delve into advanced concepts such as functional programming, macro writing, asynchronous programming, app routing, and real-time web
- Develop simple one page web applications
- Explore techniques to make your web apps aware of the external world through external or embedded database access or Oauth 2 integration
- Learn more advanced ClojureScript concepts like in app routing, real-time web
- Prepare your work for production, getting insights into optional type-checking, writing portable Clojure/ClojureScript code, and testing
In Detail
Clojure is an expressive language that makes it possible to easily tackle complex software development challenges. Its bias toward interactive development has made it a powerful tool, enabling high developer productivity.
In this book, you will first learn how to construct an interactive development experience for ClojureScript.. You will be guided through ClojureScript language concepts, looking at the basics first, then being introduced to advanced concepts such as functional programming or macro writing. After that, we elaborate on the subject of single page web applications, showcasing how to build a simple one, then covering different possible enhancements. We move on to study more advanced ClojureScript concepts, where you will be shown how to address some complex algorithmic cases. Finally, you'll learn about optional type-checking for your programs, how you can write portable code, test it, and put the advanced compilation mode of the Google Closure Compiler to good use.
Style and approach
This book is a comprehensive reference guide on ClojureScript development for the front end, and will gradually help you master interactive ClojureScript development workflows, through detailed step-by-step information illustrated with annotated code samples.
Sie lesen das E-Book in den Legimi-Apps auf:
Seitenzahl: 398
Veröffentlichungsjahr: 2016
Ähnliche
Table of Contents
Learning ClojureScript
Learning ClojureScript
Copyright © 2016 Packt Publishing
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.
Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the authors, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.
Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.
First published: June 2016
Production reference: 1290616
Published by Packt Publishing Ltd.
Livery Place
35 Livery Street
Birmingham B3 2PB, UK.
ISBN 978-1-78588-763-5
www.packtpub.com
Credits
Authors
W. David Jarvis
Rafik Naccache
Allen Rohner
Copy Editor
Pranjali Chury
Reviewer
Eduard Bondarenko
Project Coordinator
Sanchita Mandal
Commissioning Editor
Veena Pagare
Proofreader
Safis Editing
Acquisition Editor
Kirk D'costa
Indexer
Rekha Nair
Content Development Editor
Samantha Gonsalves
Production Coordinator
Aparna Bhagat
Technical Editor
Abhishek R. Kotian
Cover Work
Aparna Bhagat
Foreword
JavaScript is everywhere. The language was originally designed to permit non-programmers to add dynamic flairs to a new-fangled thing called a webpage. Two decades after its introduction, JavaScript has grown into a versatile, expressive, and complicated language—the most recent ECMAScript standard rivals the Java 1.8 language specification in terms of page count!
Yet in many ways, JavaScript still represents an older way of doing things. Nowadays, many industrial programmers are finding their way to functional programming. While JavaScript has some nice functional features, it lags far behind even the most recent decade of functional programming best practices.
Enter ClojureScript!
First released in 2011, ClojureScript has grown into an essential tool for the discerning programmer, who would love to tap into the reach offered by JavaScript, while leveraging some of best designed immutable datastructures and functional APIs in existence. Importantly, ClojureScript delivers these affordances without getting in the way of tight integration with the JavaScript host.
You can program webpages, iPhones, Androids, and Node.js, all using the same powerful Lisp programming model pioneered by John McCarthy so many years ago.
This book will show you how!
David Nolen ,
ClojureScript Lead Developer
ClojureScript has long been reliable for producing high-quality, highly-performant web applications. At the same time, the ecosystem surrounding the language has grown, both in terms of developers embracing the language and in the availability of high-quality libraries and development tools.
Also, ClojureScript's fundamental promise of reach is being proven with new use cases outside web applications; it's being used for hybrid mobile apps and new, compelling self-hosted scenarios.
In short, ClojureScript has transitioned from being a novel language taken on by early adopters to being an important and relied-upon basis for a stack that is here to stay.
It's easy to find enthusiastic community support when developing with ClojureScript. And, of course, it is tremendous help that ClojureScript is itself extremely similar to Clojure. However, one area that it lacks in is comprehensive and polished documentation, especially with respect to the coverage of the slew of pragmatic issues that accompany the development of real-world applications.
This book fills this gap by providing practical information on how to get set up and running, how to use the constructs offered by the language—most importantly, how to effectively use the available tools in day-to-day development—and how to ultimately ship your app.
We can thank Rafik, David, and Allen for sharing their hard-earned experience with us, providing a one-stop guide with answers to the gamut of questions you are likely to face when using ClojureScript. This book is a much-needed and very welcome treatment of the subject; with it, you can confidently go out and build great ClojureScript apps!
Mike Fikes ,
Author of the Planck ClojureScript REPL
About the Authors
W. David Jarvis is a software engineer living in San Francisco, California. In his spare time, he enjoys hiking, gardening, playing pool in dive bars, and overthinking everything. He is active in the open source Clojure and ClojureScript communities, and software authored by him has been downloaded over 10,000 times.
David has worked for a number of companies now living or dead, including Aggregate Knowledge, CircleCI, Standard Treasury, and Airbnb. He is currently responsible for the build, test, and deployment infrastructure at Airbnb.
The "W" is for "William" (now you know!).
While David has made the unfortunate mistake of exposing his previous scribblings to the world, this is his first actual book.
I would like to thank my companion, Kate, for her love and infinite patience in allowing this book to co-opt so many of my weekends. Without her initial support and enthusiasm, I would probably never have agreed to write the book that you are now reading.
Other debts of gratitude go to Ben Linsay (for inviting me into the technology industry), Allen Rohner (for introducing me to the joy that is Clojure), Daniel Kimerling (for being a friend in a time of need) and Keith Ballinger (for his constant wisdom and mentorship). I also owe thanks to my friends Heather Rivers and Margot Yopes, both of whom have made me a vastly better human being today than I would have been otherwise. Lastly, I would like to thank my parents and the rest of my family for providing me with a bottomless well of love and support. I am fortunate beyond words.
Rafik Naccache is a Tunisian experienced software architect and emergent technologies enthusiast. He earned his bachelors degree in computer science engineering from Tunis University of Science in 2001. Rafik fell in love with Clojure back in 2012, and he has been developing it professionally since 2013. He has occupied various positions in telecoms and banking, and he has launched some innovative internet startups in which he has been able to deploy Clojure apps. He also founded the Tunisian Clojure users community. He contributes to Open Source projects, such as Cryogen (https://github.com/cryogen-project/cryogen/graphs/contributors), Milestones (https://github.com/automagictools/milestones), and Scheje (https://github.com/turbopape/scheje). You can reach him as @turbopape on GitHub and Twitter.
First of all, I am grateful to my mom, Safia, and dad, Abdelaziz, for their love and the education that they generously gave me. It was certainly thanks to the Spectrum ZX that we had back in the eighties that I grew up as addicted to computers as I am right now, and this was the start of everything.
Warm thanks also go to my in-laws, Aunt Zohra and Uncle Hammadi, who always supported me and had blind and unconditional faith in whatever work I do, and who really wanted to see this book published.
I am very thankful to my editors, Samantha Gonsalves and Kirk D'Costa, and reviewers for their valuable advice and professional guidance towards the accomplishment of this book.
I have also special thoughts for my family, namely Tselma, Soussou, Dah, Hafedh, Zazza, Idriss and Ismael. I owe you all so much.
However, most of all, I am extremely thankful to my super wife, Khawla, who patiently had to suffer my moments away writing this book, while keeping her smile on and never complaining. I can say that this book would probably never have happened if hadn't she been there, along with our little Fatma Ezzahra and Elyes, casting their light to help brighten my hard journey towards achievement and success.
Allen Rohner is a software engineer and entrepreneur living in Austin, Texas. He is the founder of numerous startups. A few, including CircleCI, have even been successful.
Allen has been using Clojure and ClojureScript professionally since 2009, with commitments in Clojure core and dozens of other open source libraries. He has given multiple talks at Clojure/West and Clojure/conj.
Currently, Allen is working on a startup called Rasterize (https://rasterize.io), which helps companies improve conversion rate by optimizing website load times. While Allen has occasionally had blog posts go to #1 on Hacker News, this is the first 'real' book that he's collaborated on.
I'd like to thank my wife, Anna, for putting up with me on a daily basis.
About the Reviewer
Eduard Bondarenko is a software developer living in Kiev, Ukraine. He started programming using Basic on ZXSpectrum a long time ago. He works professionally in the web development domain. He has been using Ruby on Rails for many years. Sometime in 2009, he discovered Clojure, and he liked the language a lot. Except for Ruby and Clojure, he is interested in modern FP languages, machine learning, and logic programming.
www.PacktPub.com
For support files and downloads related to your book, please visit www.PacktPub.com.
eBooks, discount offers, and more
Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at [email protected] for more details.
At www.PacktPub.com , you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.
https://www2.packtpub.com/books/subscription/packtlib
Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library. Here, you can search, access, and read Packt's entire library of books.
Why subscribe?
Free access for Packt account holders
Get notified! Find out when new books are published by following @PacktEnterprise on Twitter or the Packt Enterprise Facebook page.
Preface
Welcome to Learning ClojureScript!
ClojureScript is an exciting new language that leverages Clojure's familiar syntax for the JavaScript runtime. This means that ClojureScript, like JavaScript, is a tool to help you write software applications that can either run in a client-side (browser) or server-side environment. This also means that ClojureScript inherits all of the wonderful benefits of Clojure, including Lisp macros, immutable and high-performance data structures, and beautiful functional syntax.
This book aims to serve as an introduction to both the core and advanced concepts of ClojureScript development with the ultimate objective of teaching you how to build single-page web applications. Whatever your background and prior level of experience with either Clojure or ClojureScript, it is our hope that this book will prove to be an invaluable aid to you in learning how to develop ClojureScript programs for the modern web.
We've structured the book in such a way as to take you through on a soft progression. Beginning with the basics of getting your interactive environment set up, we'll take you all the way through advanced subjects such as logic programming and designing your applications to use Om, a ClojureScript wrapper for Facebook's React framework. By the end of this book, you should have a deep understanding of the complete process of developing modern single-page web apps with ClojureScript, and you should feel comfortable writing applications that you know how to configure and deploy in production environments.
What this book covers
Chapter 1, Getting Ready for ClojureScript Development, covers preparing an interactive development environment for the browser as well as some basic configuration options.
Chapter 2, ClojureScript Language Fundamentals, describes the basic syntax and building blocks of the ClojureScript language.
Chapter 3, Advanced ClojureScript Concepts, focuses on idiomatic functional programming, ClojureScript macros, and concurrent software design.
Chapter 4, Web Applications Basics with ClojureScript, covers working with the DOM, CSS, and HTML5 elements.
Chapter 5, Building Single Page Applications, teaches you how to make web applications that interact with third-party data providers, such as remote databases, OAuth providers, or embedded data stores.
Chapter 6, Building Richer Web Applications, covers more advanced topics, such as WebSockets, routing for single-page applications, and building applications using Om—a ClojureScript wrapper for React.
Chapter 7, Going Further with ClojureScript, showcases various core and third-party libraries that provide elegant and unique solutions to problems such as pattern matching, data validation, and logic solving.
Chapter 8, Bundling ClojureScript for Production, focuses on the tools that are necessary to properly package your ClojureScript libraries and applications for production usage. This chapter covers testing, compiler optimizations, and how to containerize your applications.
What you need for this book
In order to be able to run some of the example code in this book, you'll need a computer that is capable of running at least Java 6, and preferably Java 7 or 8. Oracle maintains a detailed list of hardware and software requirements for the latest versions of Java online at http://java.com/en/download/help/sysreq.xml. However, most modern laptop and desktop computers should be capable of running the latest version of Java without a problem. You'll also need a browser and an internet connection in order to download the relevant software and dependencies that are needed. For a browser, we recommend Google Chrome, but any modern web browser will do just fine.
Who this book is for
This book is for web application developers who want to benefit from the power of ClojureScript to get an agile and highly-productive development platform that targets mainly browser JavaScript.
You are not required to be fluent in Clojure, but it will be easier for you if you have a basic understanding of browser or server-side JavaScript.
Conventions
In this book, you will find a number of text styles that distinguish between different kinds of information. Here are some examples of these styles and an explanation of their meaning. Code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles are shown as follows: "The def statement tells us that what follows will be a definition."
A block of code is set as follows:
(ns example-code) cljs.user=> (+ 1 1) ;; => 2 cljs.user=> (* 2 3) ;; => 6When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:
(ns example-code) cljs.user=> (+ 1 1) ;; => 2 cljs.user=> (* 2 3) ;; => 6 cljs.user=> (/ 9 3);; => 3Any command-line input or output is written as follows:
cljs.user=> (map inc [1 2 3 4 5]);; => (2 3 4 5 6)New terms and important words are shown in bold. Words that you see on the screen, for example, in menus or dialog boxes, appear in the text like this: "If we check the page, we should see our Page rendered! alert logged to the console."
Note
Warnings or important notes appear in a box like this.
Tip
Tips and tricks appear like this.
Reader feedback
Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or disliked. Reader feedback is important for us as it helps us develop titles that you will really get the most out of.
To send us general feedback, simply e-mail [email protected], and mention the book's title in the subject of your message.
If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide at www.packtpub.com/authors.
Customer support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Downloading the example code
You can download the example code files for this book from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
You can download the code files by following these steps:
You can also download the code files by clicking on the Code Files button on the book's webpage at the Packt Publishing website. This page can be accessed by entering the book's name in the Search box. Please note that you need to be logged in to your Packt account.
Once the file is downloaded, please make sure that you unzip or extract the folder using the latest version of:
The code bundle for the book is also hosted on GitHub at https://github.com/learningclojurescript/code-examples. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!
Errata
Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you could report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/submit-errata, selecting your book, clicking on the Errata Submission Form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded to our website or added to any list of existing errata under the Errata section of that title.
To view the previously submitted errata, go to https://www.packtpub.com/books/content/support and enter the name of the book in the search field. The required information will appear under the Errata section.
Piracy
Piracy of copyrighted material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works in any form on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.
Please contact us at [email protected] with a link to the suspected pirated material.
We appreciate your help in protecting our authors and our ability to bring you valuable content.
Questions
If you have a problem with any aspect of this book, you can contact us at [email protected], and we will do our best to address the problem.
Chapter 1. Getting Ready for ClojureScript Development
ClojureScript's promise is to bring the expressiveness and agility of the Clojure programming language to JavaScript developers. Having such power at hands means that teams working on single page applications—and on Node.js services as well—more productivity and less frustration.
But to be able to take complete advantage of this platform, we must grasp its inner mechanisms and, sometimes patiently, work our way towards the perfect ClojureScript live-coding environment. In this chapter, we'll cover the material necessary to achieve this objective.
We'll begin by studying the ClojureScript ecosystem, focusing on its compiler internals and talking about the Read-Eval-Print-Loop (REPL) it offers. We'll then present some alternative building blocks that make it possible to expose interactive ClojureScript development work-flows through third-party tools. We'll finally leverage all of this knowledge in order to build full-fledged, integrated, and interactive ClojureScript development environments. To get started with adopting this approach, we'll discuss the following:
Getting familiar with the ClojureScript ecosystem
At the heart of the ClojureScript's ecosystem lies the compiler. In this section, we'll gain an insight into its internals: what is its underlying architecture, how does it work, and how can its functioning be tweaked in order to allow for leaner ClojureScript development?
Inside the ClojureScript compiler
The ClojureScript compiler is a piece of Clojure software packaged as a JAR along with Clojure itself, so the package is self-contained and can be manipulated easily. As such, the ClojureScript compiler requires the JVM for its operation. Currently, as ClojureScript developers have baked in the compiler, among many other things, an integration mode for Nashorn, the Java 8 embedded JavaScript engine, they recommend using the same version of the JVM. But, Java 7 is sufficient for the sole operation of the compiler.
Note
A bootstrapped version of ClojureScript, that is, one that uses pure ClojureScript for compilation, has recently been released. Cljs-bootstrap ( https://github.com/swannodette/cljs-bootstrap ), at the time of writing this, is still a work in progress, and offers worse performance than the JVM mainstream compiler. Besides, bootstrapped ClojureScript does not allow for the advanced compilation flags that its JVM counterpart offers.
At its most stripped down definition, the compiler accepts ClojureScript code, that is, mainly s-expressions obeying some Clojure subset semantics, and emits JavaScript artifacts that are passed on to the Google Closure Library ( https://developers.google.com/closure/ ) in order to get it "polished".
The Google Closure Library is a set of JavaScript optimizing tools open sourced by Google, which it uses to support the development of its JavaScript-rich applications, such as Gmail or Maps. Using this library has the following benefits:
Now, let's see the ClojureScript compiler in action. To understand its fundamentals, we won't use any build-automation tooling such as Leiningen for the moment, though we'll for sure need it to construct our tooling later on. Let's begin by downloading the latest release of the compiler (1.7.48 as of the time of writing):
Note
Throughout this book, we assume that you are working on a POSIX compatible system, such as Linux or Mac OS X.
Create a new directory for your first project, label it cljs_first_project, and then download into it the compiler JAR:
mkdir cljs_first_project; cd cljs_first_projectwget \https://github.com/clojure/clojurescript/releases/download/r1.7.48/cljs.jarOnce the compiler JAR is downloaded, you'll need to create a source directory and the path for your first namespace inside the project folder:
mkdir -p src/cljs_first_project; cd src/cljs_first_projectNow it's time to write your first ClojureScript namespace, which must conform to the path we're currently in (note that you should replace the underscores with dashes in the directory name). Type the following code in a file named core.cljs:
(ns cljs-first-project.core) (js/alert "Hello world!")This code just declares a namespace and the only operation that our program does is showing an alert popup with the familiar "Hello World!" greeting.
Now with the ClojureScript compiler being a Clojure library, we must write some Clojure code in order to trigger the building of the ClojureScript code we just wrote. Create a Clojure file at the root of our project (at the same level as the /src directory) and label it build.clj with the following Clojure code in it:
(require 'cljs.build.api) (cljs.build.api/build "src" {:output-to "out/main.js"})Building ClojureScript is a matter of requiring the cljs.build.api namespace and then launching the build function that takes two arguments. The first argument is where to look for the ClojureScript source code to build, that is the src directory in our case, and second one is where to output the result JavaScript; out/main.js as far as this example is concerned.
With this helper Clojure program under our belt, we can launch the ClojureScript compilation process. It is about launching the embedded Clojure from the JAR we downloaded and passing to it the build program we just wrote. When we run Clojure this way, we make sure that the ClojureScript facilities are loaded, especially the cljs.build.api namespace. To be able to achieve this, we'll have to add the JAR we downloaded as well as the src directory to the classpath when we invoke Clojure with the help of the java command:
java -cp cljs.jar:src clojure.main ./src/build.cljAfter you've run this command, you'll notice that an out directory containing our target main.js file has just been created. In order to launch the output JavaScript artifact, we'll need an HTML page, which when loaded into our browser will greet us with a popup. On our HTML page, we must surely load the generated main.js file, but we must also bootstrap the Google Closure Library by loading the out/goog/base.js script.
Also, note that the main.js file only contains a description of the different namespaces' dependencies managed by the Google Closure Library and no logic of execution. So, we must explicitly set an entry point to our program by telling the Google Closure Library to require a namespace to start with, and that's our cljs_first_project.core namespace (note how the dashes got transformed to underscores in the HTML page). Here's what the HTML page, which we'll store under the greet.html file, at the root folder of your project, looks like:
<html> <body> <script type="text/javascript" src="out/goog/base.js"></script> <script type="text/javascript" src="out/main.js"></script> <script type="text/javascript"> goog.require("cljs_first_project.core"); </script> </body> </html>Accessing this page from your browser greets you with a JavaScript alert popup. Congratulations! You've successfully written and compiled your first ClojureScript program!
There are more advanced ways to work with the architecture of the build process. For example, to get rid of all the goog requires in your HTML page, you can tell the compiler in your Clojure build program which namespace should be set as an entry point, as follows:
(require 'cljs.build.api) (cljs.build.api/build "src" {:main 'cljs-first-project.core :output-to "out/main.js"})This lets you strip the necessary script declarations in your greet.html page down to the following:
<html> <body> <script type="text/javascript" src="out/main.js"></script> </body> </html>Another way to optimize the build process is to set the auto-build of your ClojureScript code on. The compiler can be triggered to be on the watch mode, thus recompiling the output JavaScript as soon as it observes any changes in the src directory. Set your Clojure build program to use the watch function instead of build, as shown here:
(require 'cljs.build.api) (cljs.build.api/watch "src" {:main 'first-cljs-project.core :output-to "out/main.js"})We've taken quite a deep dive inside the compiler. But, to be able to keep the promise of bringing agile development to JavaScript land, ClojureScript ought to offer a REPL to its users, as any decent lisp would do. Let's discover how ClojureScript addresses this matter in the next section.
Working with the ClojureScript REPL
ClojureScript comes bundled with REPL support for the browser, Node.js, Rhino, and Nashorn. The REPL functionality can be triggered through a call to the repl function from the cljs.repl namespace present in the ClojureScript JAR. Just as we did for the building process, we must create a REPL launching Clojure program. In this program, we begin by building our project and then launch the interactive REPL session. Create a repl.clj Clojure program containing the following listing:
(require 'cljs.repl) (require 'cljs.build.api) (require 'cljs.repl.browser) (cljs.build.api/build "src" {:main 'cljs-first-project.core :output-to "out/main.js" :verbose true}) (cljs.repl/repl (cljs.repl.browser/repl-env) :watch "src" :output-dir "out")Here, we'll build a REPL with evaluation on the browser, as we've used the cljs.repl.browser namespace. Note how we set the :watch option, so our REPL automatically gets fresh versions of the output JavaScript, providing for interactive ClojureScript code evaluation. The :output-dir directive tells the REPL where to look for generated artifacts so that they can be loaded into the relevant evaluation environment. As the interactive evaluation session goes, output of the compilation goes into out/watch.log, so we can follow along what's going on while the code interacts with the REPL.
Now, you must set a connection to the REPL inside your ClojureScript program, core.cljs. Once built, the resulting JavaScript program will stay in tune with the REPL environment, by pushing to the browser any changes made to the ClojureScript source:
(ns cljs-first-project.core (:require [clojure.browser.repl :as repl])) (defonce conn (repl/connect "http://localhost:9000/repl")) (js/alert "Hello world!")The connection has been defined with the defonce parameter to make sure that the same connection is used across the many builds that will occur while the user interacts with the REPL and triggers a new build per evaluation.
Now, launch the REPL, preferably using the rlwrap command, so the display on the terminal is properly rendered:
rlwrap java -cp cljs.jar:src clojure.main repl.cljBe patient while the first build, involving the construction of the connection to the REPL, is completed. When it completes, you'll see the Waiting for browser to connect message in your terminal. Once you see this message, point your browser to the HTML page we prepared before (greet.html) now through http://localhost:9000/greet.html. Accept the first greeting popup and go back to your terminal; you'll see the following output:
Watch compilation log available at: out/watch.log To quit, type: :cljs/quit cljs.user=>Type another greeting to see if it gets automatically executed in your browser. Type in your REPL the following:
cljs.user=> (js/alert "Hello World From REPL!")You'll see new greetings from the REPL interactively popping up without hitting refresh on your browser:
So far, were able to come up with a ClojureScript REPL that empowered us to interact with the browser. But, we are far from having a full-fledged development environment yet; the terminal through which we are coding is quite limited, and we lack several essential features such as code completion, syntax coloring, source code exploration, refactoring, or version control management to name a few. We need a much more complete and fluid coding experience and that's what we will strive to achieve in the next sections. We'll begin by exploring the two most promising facilities that permit text editors or integrated development environments to take advantage from the ClojureScript REPL. Then, we'll showcase two Emacs setups based on those facilities-one based on CIDER and another one backed byinf-clojure.
Live coding ClojureScript on top of nREPL with Piggieback and Weasel
Network REPL (nREPL) ( https://github.com/clojure/tools.nrepl ) is a Clojure library designed primarily to offer remote Clojure code evaluation. It follows a client-server architecture in which the server exposes the REPL functionality by responding to client code evaluation queries. nREPL has been created to offer a means to the makers of development tools to connect and explore running Clojure environments in a way that is agnostic to the platform these tools may be running on.
Many prominent Clojure development tools rely on nREPL to implement their functionality. In fact, CIDER on Emacs or Cursive on Intellij IDEA, the most used tools for developing Clojure at the time of writing this, both rely on nREPL (CIDER relying more on nREPL for code introspection than Cursive).
Naturally, ClojureScript also benefits from nREPL.
Piggieback ( https://github.com/cemerick/piggieback ) is an nREPL middleware that seizes this opportunity. Piggieback hooks into nREPL and changes its operation so it can evaluate and load ClojureScript code, while being understandable to the vast majority of existing Clojure tooling. In the next section, we'll take a closer look at Piggieback.
Working with Piggieback
Piggieback changes the nREPL behavior to turn it into a ClojureScript remote evaluation environment. It does this by functioning as a middleware layer on top of nREPL. Let's see how to do this using Leiningen.
Note
Leiningen, the Clojure build tool, can be downloaded from http://leiningen.org/ or https://github.com/technomancy/leiningen . You can also find detailed instructions and documentation on how to install and get started with Leiningen on both the sites. We'll be using Leiningen a lot in this book, so you'll definitely want to install it.
We'll use this project management tool to create a new Clojure project:
lein new piggieback_projectThen, we'll have to modify the project.clj file (where project-specific configuration is kept) in order to turn our project into a ClojureScript one, adding ClojureScript as a dependency:
(defproject piggieback_project "0.1.0-SNAPSHOT" :description "FIXME: write description" :url "http://example.com/FIXME" :license {:name "Eclipse Public License" :url "http://www.eclipse.org/legal/epl-v10.html"} :dependencies [[org.clojure/clojure "1.8.0"] [org.clojure/clojurescript "1.8.51"]])7.228"]])Now, it is time to add Piggieback into the mix. Add its dependencies and its middleware to the project.clj file:
(defproject piggieback_project "0.1.0-SNAPSHOT" :description "FIXME: write description" :url "http://example.com/FIXME" :license {:name "Eclipse Public License" :url "http://www.eclipse.org/legal/epl-v10.html"} :dependencies [[org.clojure/clojure "1.8.0"] [org.clojure/clojurescript "1.7.228"]] :profiles {:dev {:dependencies [[com.cemerick/piggieback"0.2.1"] [org.clojure/tools.nrepl"0.2.10"]] :repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}}})Piggieback is just an entry point to ClojureScript REPLs. Once we hook into our nREPL, we can operate in the same manner as we did when we were working with the REPL bundled with the compiler. Once again, we'll need to prepare a ClojureScript namespace that can define the connection to the REPL, and an HTML page that we can load into our browser. Create a core.cljs file under the src/piggieback_project folder:
(ns piggieback-project.core (:require [clojure.browser.repl :as repl])) (defonce conn (repl/connect "http://localhost:9000/repl"))Next, copy the greet.html file we wrote previously into the root of your new project.
We can now start an nREPL session. Type the following at the root of your project:
lein replIn order to launch interactive code evaluation and loading in the browser, we must use some ClojureScript namespaces as to be able to hook Piggieback into our running nREPL session. We'll need to build the ClojureScript program we wrote at least once, so first we'll have to load the compiled JavaScript code to connect to the nREPL. Issue the following commands at the running REPL prompt:
user=> (require 'cljs.build.api)user=> (cljs.build.api/build "src" #_=> {:main 'piggieback-project.core #_=> :output-to "out/main.js" #_=> :verbose true})user=> (require 'cljs.repl.browser)We are now ready to hand over the code evaluation responsibility to Piggieback. Type the following:
user=> (cemerick.piggieback/cljs-repl (cljs.repl.browser/repl- env))You'll see that a JavaScript compilation process has been launched. It is our core.cljs file being compiled, and constructing a connection to the REPL. This will be our nREPL session—accessed through the JavaScript artifacts loaded via the greet.html page.
Once this operation has finished, you'll get the Waiting for browser to connect message that we previously encountered during our interaction with the REPL built by the ClojureScript compiler. As soon as you point your browser to http://localhost:9000/greet.html, you'll notice that the prompt has changed; it now shows the following:
cljs.user=>_This means that the nREPL session has started accepting code to be compiled. The compiled JavaScript will automatically be evaluated on the connected browser. Try to generate a Hello World! popup from the browser from Piggieback this time:
cljs.user=> (js/alert "Hello World from Piggieback!")And your browser says it with a popup, from your nREPL/Piggieback session.
We've now seen how we can change the nREPL's behavior so that it is turned into an entry point to the ClojureScript REPL. Code passed to the REPL executed on into the JavaScript environment-the browser in our context-via JavaScript files that are regenerated after each and every operation.
We can make this workflow even leaner by hot loading the JavaScript artifacts into the browser with websockets. This is what we will see in the next section, with the Weasel library.
Setting up Weasel with PiggieBack for browser live coding
Weasel ( https://github.com/tomjakubowski/weasel ) sets a up realtime communication channel using a websocket between a ClojureScript REPL and the JavaScript evaluation environment. The authors of this library say that choosing websockets as a means for delivering compiled JavaScript to runtime environments made it possible for them to profit from a simple and reliable transport. It also empowered them to reach a much wider range of JavaScript engines, especially those that don't properly support, the <iframe> tag (the main technology behind the vanilla ClojureScript browser REPL). Let's now add Weasel on top of the Piggieback-enabled nREPL environment that we've set up in the previous sections.
Let's first modify the piggieback_project file we worked on earlier to support Weasel by adding its dependency to the project.clj file:
(defproject piggieback_project "0.1.0-SNAPSHOT" :description "FIXME: write description" :url "http://example.com/FIXME" :license {:name "Eclipse Public License" :url "http://www.eclipse.org/legal/epl-v10.html"} :dependencies [[org.clojure/clojure "1.8.0"] [org.clojure/clojurescript "1.7.228"] [weasel "0.7.0" :exclusions [org.clojure/clojurescript]]] :profiles {:dev {:dependencies [[com.cemerick/piggieback"0.2.1"] [org.clojure/tools.nrepl "0.2.10"]] :repl-options {:nrepl-middleware [cemerick.piggieback/wrap- cljs-repl]}}})Let's modify our ClojureScript code so that it can connect to the websocket opened by Weasel:
(ns piggieback-project.core (:require [weasel.repl :as repl])) (when-not (repl/alive?) (repl/connect "ws://localhost:9001"))Just like we did in the previous section, we'll need to connect to our nREPL and plug Piggieback in on top of it, but this time, we'll run it with a Weasel browser. After making sure that you are at the root of the project folder, type in a terminal:
lein replFirst, let's compile our ClojureScript source so we have our JavaScript ready to connect to the format as code websocket. Run the following from your nREPL session:
user=> (require 'cljs.build.api)user=> (cljs.build.api/build "src" #_=> {:main 'piggieback-project.core #_=> :output-to "out/main.js" #_=> :verbose true})Next, we require the Weasel REPL namespace:
user=> (require 'weasel.repl.websocket)We hook Piggieback onto the current session and ask it to use the Weasel websocket as the REPL environment (we also set the IP address and the port we want our websocket to be listening to):
user=> (cemerick.piggieback/cljs-repl #_=> (weasel.repl.websocket/repl-env :ip "0.0.0.0" :port 9001))After Piggieback is launched, Weasel shows a message to inform us that it is awaiting incoming connections:
<< waiting for client to connect ...Open the greet.html file in your browser (you need to open it from the files manager on your OS, as we are not serving it over HTTP this time!). As soon as the file opens, you see the following message in your nREPL session:
<< waiting for client to connect ... connected! >>The prompt in your nREPL session should change to the following:
cljs.user=> _As usual, let's salute the world and see if our greeting pops up in the browser:
cljs.user=> (js/alert "Hello World from Weasel!")Your browser should now emit an alert with a greeting message on it.
Until this point, we have been able to put together a powerful environment for developing ClojureScript. Thanks to Piggieback being hooked on nREPL, we can benefit from the integrated development tools that already exist for Clojure. Before we go too much further on this subject, let's see how we can write ClojureScript programs that target other JavaScript environments. In the following section, we'll focus on setting up a Piggieback powered nREPL that evaluates code on the Node.js platform.
ClojureScript REPLs on Node.js with Piggieback
Setting up Node.js REPLs is simpler than targeting the browser. You don't need to set up connections from the REPL process to the browser with the help of some vanilla JavaScript. All you have to do is make sure that the source is compiled, and set the REPL target to Node.js, so that the compiled output is handed over to that evaluation environment for running.
First, make sure that Node.js is installed. Under piggieback_project, change the core.cljs file so that it looks like the following:
(ns piggieback-project.core (:require [cljs.nodejs :as nodejs])) (nodejs/enable-util-print!) (defn -main [& args] (println "Hello world from Node.js!")) (set! *main-cli-fn* -main)Launch an nREPL session for your project by typing the following:
lein replWe then require the namespaces necessary for the launch of our Node.js REPL:
user=>(require 'cljs.build.api)user=> (require 'cljs.repl.node)Now, launch the first build of our ClojureScript core.cljs source:
user=> (cljs.build.api/build "src" #_=> {:main 'piggieback-project.core #_=> :output-to "out/main.js" #_=> :verbose true})We can now hook a Piggieback REPL into this running nREPL session. Issue the following command:
(cemerick.piggieback/cljs-repl (cljs.repl.node/repl-env))The nREPL session responds with a message saying that a Node.js REPL has been launched:
ClojureScript Node.js REPL server listening on 49449And as usual, the prompt has been changed so as to notify us that we have successfully launched a ClojureScript REPL on top of our nREPL session:
cljs.user=> _At this point, we can implement a program similar to the Node.js "Hello World," a little HTTP server that greets the browser that queries it. Type the following in your, now, ClojureScript-enabled nREPL session (we'll elaborate more on the syntax later on):
cljs.user=> (def http (js/require "http"))cljs.user=> (.listen (.createServer http #_=> (fn [req res] #_=> (do #_=> (.writeHead res #_=> 200 #_=> (js-obj #_=> "Content-Type" "text/plain")) #_=> (.end res #_=> "Hello World from Node.js http server!")))) #_=> 1337 #_=> "127.0.0.1")If you navigate your browser to http://127.0.0.1:1337, you should see the greeting from your Node.js server.
In the next section, we'll elaborate on a new contender in the realm of interactive ClojureScript coding environments: Figwheel, the new kid on the block that gets you to a ClojureScript browser REPL quickly.
Live coding ClojureScript with Figwheel
Figwheel ( https://github.com/bhauman/lein-figwheel ) is a Leiningen plugin that builds ClojureScript programs and delivers them to the browser for interactive evaluation. In contrast with nREPL-based work-flows, Figwheel does not rely on third-party REPLs. It is a self-contained library with its own ClojureScript REPL that relies on websockets to push your work to the browser as you edit your ClojureScript code. Figwheel also supports CSS live reloading in the browser, hence providing for a completely interactive web development experience. In this next section, we'll use Figwheel to get set up a ClojureScript live-coding experience on the browser.
Setting up Figwheel for browser live coding
Figwheel comes as a self-contained library that automatically builds and loads the generated JavaScript into the browser. This means we won't have to manually build the JavaScript that'll be pushed to the browser in order to establish the connection to the Figwheel REPL. Everything will be handled for us.
Let's begin by creating a new project that we will use to experiment with Figwheel:
lein new figwheel-projectWe'll now need to change our project.clj file so that our project is aware of the lein-figwheel plugin:
(defproject figwheel-project "0.1.0-SNAPSHOT" :dependencies [[org.clojure/clojure "1.8.0"] [org.clojure/clojurescript "1.8.51"]] :plugins [[lein-figwheel "0.5.1"]] :clean-targets [:target-path "out"] :cljsbuild { :builds [{:id "dev" :source-paths ["src"] :figwheel true :compiler {:main "figwheel-project.core"}}]}) :asset-path "js/out" :output-to "resources/public/js/main.js" :output-dir "resources/public/js/out"}}]})Create a file named core.cljs under src/figwheel_project/ so we can have a ClojureScript program that will be built and pushed to the browser. Code changes will be pushed to the browser automatically later on via this loaded file:
(ns figwheel-project.core) (js/alert "Hello from Figwheel!")As before, in order to load the compiled JavaScript that'll connect our browser to the running Figwheel process we need to have an HTML page. Since we're still compiling ClojureScript to the main.js
