Guide · Open source
How to use Cycle.js: install, structure an app and learn the basics
Updated · written with AI from the project's own documentation and checked against our catalogue data
Cycle.js is an open-source JavaScript framework, licensed under MIT, for building web apps in a functional, reactive style. This guide explains how its model works, which packages you combine to build an app, and how to get started, based on the project README. It is written for developers who already know JavaScript and are curious about reactive streams.
Cycle.jscyclejs/cyclejs · ★ 10.2k · MIT Install options & downloads Quick start
- 1Read the official docs. Start at cycle.js.org, which the README names as the main learning resource.
- 2Install Node.js and npm. These are the prerequisites listed in the source.
- 3Get the source if needed. Clone the repository with git clone https://github.com/cyclejs/cyclejs.git to read the packages.
- 4Pick your stream library. Choose @cycle/run for the default setup, or @cycle/rxjs-run or @cycle/most-run if you use RxJS or most.js.
- 5Install the @cycle packages you need. Add packages such as @cycle/dom and @cycle/run to your project.
- 6Write a pure main function. Map input streams to output streams and pass drivers to run.
What Cycle.js is and how it is structured
In Cycle.js, your app is written as a pure function. The function takes input streams, such as user events or HTTP responses, and returns output streams. Keeping side effects separated this way is what the project means by predictable code.
The project is split into small, specialized packages. The README notes that the npm package @cycle/run lives in the directory run of the repository, and that each package is summarized in a table there.
- @cycle/dom: DOM rendering and event handling
- @cycle/http: HTTP requests and responses
- @cycle/history: browser history and routing
- @cycle/html: HTML support
- @cycle/isolate: isolation of components
- @cycle/run: runs your app with the drivers you provide
- @cycle/rxjs-run, @cycle/most-run: variants that use RxJS or most.js
Install Cycle.js with npm
The source lists Node.js and npm as the prerequisites, and a package-manager install method. The README's install command shown here clones the repository with git. For a project, you install the @cycle packages you need through npm.
Check the official documentation at cycle.js.org for the current install steps, since the README points there for learning material.
- Install Node.js and npm first.
- Install the @cycle packages your app needs, for example @cycle/run and @cycle/dom.
git clone https://github.com/cyclejs/cyclejs.gitUnderstand streams, drivers and the main function
Cycle.js apps connect your main function to the outside world through drivers. A driver handles a side effect, such as the DOM or HTTP, and turns it into streams your app can read from and write to.
Because the main function only deals with streams, you can test the data flow without a browser. The source describes this explicit, testable flow as a main benefit for teams.
- Write the main function as a pure function from input streams to output streams.
- Pass drivers, such as the DOM driver from @cycle/dom, to the run function from @cycle/run.
- Use the stream libraries you already know, such as RxJS, xstream or most.js.
Choose the right stream library
The packages @cycle/rxjs-run and @cycle/most-run exist alongside @cycle/run. The README lists RxJS, most and xstream as important stream library dependencies, which it shows at their latest versions.
If you already use one of these libraries, pick the matching run package so your code stays in a familiar style.
Where to get help
The README points to the official documentation at cycle.js.org as the main learning resource. For questions, it lists a StackOverflow tag, a Gitter chat and GitHub issues. Bug reports go to GitHub issues.
The README says discussion-style issues are labeled and closed, and that only actual issues are left open.
- Learn: cycle.js.org
- Ask: StackOverflow tagged cyclejs, or the Gitter chat
- Report bugs: GitHub issues
What people use it for
- Building a front-end UI where user events and state changes are modeled as streams
- Writing an app whose HTTP calls are handled as streams via @cycle/http
- Structuring a team codebase so data flow is explicit and easy to test
- Exploring functional programming applied to user interfaces
Frequently asked questions
Is Cycle.js free to use?
Yes. The repository is licensed under MIT, a permissive open-source licence. Check the LICENSE file in the repository for the full terms.
What do I need to install Cycle.js?
The source lists Node.js and npm as the prerequisites. Install them, then add the @cycle packages you need to your project.
Is Cycle.js an alternative to React or Vue?
The project lists React, Vue and RxJS as comparable projects. Cycle.js differs in its functional, stream-based model, where the app is a pure function from input streams to output streams.
Is Cycle.js good for beginners?
The README points mainly to official docs and a chat channel rather than a large ecosystem. It suits developers who already know reactive streams such as RxJS, xstream or most.js.
Where can I get help if I get stuck?
The README lists a StackOverflow tag for questions, a Gitter chat, and GitHub issues for bugs. The official docs at cycle.js.org are the main learning resource.
Does Cycle.js have many ready-made UI components?
The README does not describe a large library of off-the-shelf components, so check the packages list and the official docs before committing to it for a project that needs many ready-made parts.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Cycle.js suits developers who already know reactive streams and want explicit, testable data flow in front-end code. If you are a beginner who wants a large, widely documented ecosystem or many ready-made components, a mainstream framework such as React or Vue is a safer choice.
Install options & downloads