docs/dist/flummox/data/docs/index.json
{"path":"index","content":"Flummox\n=======\n\n[](https://travis-ci.org/acdlite/flummox)\n[](https://codeclimate.com/github/acdlite/flummox)\n[](https://www.npmjs.com/package/flummox)\n[](https://www.npmjs.com/package/flummox)\n\nIdiomatic, modular, testable, isomorphic Flux. No singletons required.\n\n```\n$ npm install --save flummox\n```\n\nJoin the **#flummox** channel of the [Reactiflux](http://reactiflux.com/) Slack community.\n\n[](https://gitter.im/acdlite/flummox?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)\n\n* [API documentation](flummox/docs/api.md)\n* [Quick start guide](flummox/docs/guides/quick-start.md)\n* [React integration guide](flummox/docs/guides/react-integration.md)\n\nFeatures\n--------\n\n- No singletons = isomorphism for free!\n- Robust yet minimal API inspired by React and ES6\n- Tiny. **~3.8kb (compressed and gzipped)**.\n- The dispatcher and constants are implementation details — no need to interact with them unless you want to.\n- Async actions [made simple with promises](flummox/docs/api/actions#asynchronous-actions). Pairs well with async-await, or your favorite promise library.\n- Easy [integration with React](flummox/docs/guides/react-integration) via fluxMixin and FluxComponent.\n- Support for [plain JavaScript class components](http://facebook.github.io/react/blog/2015/01/27/react-v0.13.0-beta-1.html) in React 0.13.\n- Serialization/deserialization of stores, for faster page loads.\n- Centralized [debugging](flummox/docs/api/flux).\n- \"It's Just JavaScript\" — supports CoffeeScript, TypeScript, and any other compile-to-JS language.\n\n**Version 3.0 with official support for React 0.13 has been released! See the [changelog](https://github.com/acdlite/flummox/blob/master/CHANGELOG.md) and [upgrade guide](https://github.com/acdlite/flummox/blob/master/UPGRADE_GUIDE.md) for more information.**\n\n**Pssst...** Want to see an example of an isomorphic Flummox app? You're looking at one right now! [Check out the source](https://github.com/acdlite/flummox/tree/master/docs) to see how it's made.\n\nThe big idea\n------------\n\nThere are *sooo* many Flux libraries out there. What makes Flummox special?\n\nFlummox allows you to encapsulate your entire Flux set-up — stores, actions, constants, and the dispatcher — into a single class, with **zero singletons or global references**. It's as easy as\n\n```js\nconst flux = new Flux();\n```\n\nThere are many benefits to this approach, but the biggest one is that it makes isomorphism (running the same code on both the server and the client) incredibly straightforward.\n\n**Flummox is not a framework.** Rather than forcing a bunch of new concepts and complicated APIs upon you, Flummox embraces existing idioms from Flux, React, and ES6 — without being too prescriptive.\n\n#### Simple example\n\n\n```js\nimport { Actions, Store, Flummox } from 'flummox';\n\nclass MessageActions extends Actions {\n newMessage(content) {\n return content; // automatically dispatched\n }\n}\n\nclass MessageStore extends Store {\n constructor(flux) {\n super();\n\n const messageActions = flux.getActions('messages');\n this.register(messageActions.newMessage, this.handleNewMessage);\n this.messageCounter = 0;\n\n this.state = {};\n }\n\n handleNewMessage(content) {\n const id = this.messageCounter++;\n\n this.setState({\n [id]: {\n content,\n id,\n },\n });\n }\n}\n\nclass Flux extends Flummox {\n constructor() {\n super();\n\n this.createActions('messages', MessageActions);\n this.createStore('messages', MessageStore, this);\n }\n}\n\nconst flux = new Flux();\n\n// perform action\nflux.getActions('messages').newMessage('Hello, world!');\n```\n\n### Idiomatic\n\nIf you know Flux, you know Flummox. If you're not familiar with Flux, there are [many](http://facebook.github.io/flux/docs/overview.html#content) [great](https://medium.com/brigade-engineering/what-is-the-flux-application-architecture-b57ebca85b9e) resources available to get you up to speed.\n\nThe primary goal of Flummox is reduce the boilerplate involved in setting up Flux for your application, so the API has been kept as minimal and predictable as possible. It uses Facebook's dispatcher under the hood. It encourages (but does not require) the use of ES6 classes. The state API for stores mirrors the state API for React components. Everything works as you'd probably expect.\n\n### Modular\n\nThere are three classes in Flummox: Store, Actions, and Flux. They are completely independent from each other. For example, you can create a new Store without ever touching Flux or Actions. You can extend them, modify them, add mixins — if it's possible with JavaScript, you can do it.\n\nExamples in this document use ES6 class notation, but that's a pattern, not a requirement: underneath the hood, it's just JavaScript prototypical inheritance. It's compatible with CoffeeScript, TypeScript, and regular ES5 right out of the box.\n\n### Testable\n\nBecause Flummox does not rely on singletons, and each of the different classes can be instantiated independently from the others, it's really easy to write tests. A good example can be found in Flummox's own [test suite](https://github.com/acdlite/flummox/blob/master/src/__tests__/Store-test.js).\n\n### Isomorphic\n\nThis is a big one, and one of the biggest motivating factors for creating this library. Isomorphism is tricky or impossible in many other Flux libraries because they rely on singleton objects, spread out across multiple modules. Often they force you to use a separate API.\n\nAgain, because Flummox does not rely on singletons, you get isomorphism for free: just create a new Flux instance on each request! Here's a very basic example how that might look using Express and React:\n\n```js\n\n// shared/Flux.js\nclass Flux extends Flummox { ... }\n\n// server/app.js\napp.get(\"/\", function(req, res) {\n const flux = new Flux();\n\n res.send(\n React.renderToString(<App flux={flux} />)\n );\n});\n```\n\nFlummox also gives you the ability to serialize the initial state of your application on the server, send it down to the client as a string, and deserialize it before the initial render. While not required for isomorphism, it helps make the initial page load snappy by reducing unnecessary AJAX requests to the server.\n\nReact integration\n-----------------\n\nIntegrating Flummox with React is really easy. You can do it the long way by manually adding and removing event listeners, but that leads to a lot of boilerplate. Use FluxComponent and/or fluxMixin to subscribe to store changes.\n\nHere's a basic example:\n\n```js\nimport React from 'react';\nimport FluxComponent from 'flummox/component';\n\nclass OuterComponent extends React.Component {\n render() {\n return (\n // Pass an array of store keys, or a map of keys to state getters\n <FluxComponent connectToStores={['storeA', 'storeB']}>\n <InnerComponent />\n </FluxComponent>\n );\n }\n}\n```\n\nYou can subscribe to subsets of store state using custom state getters. Read all about it in the [React integration guide](flummox/docs/guides/react-integration).\n\n\nRoadmap\n-------\n\nFlummox is still quite new, but the core features are already in place. A big focus right now is improving the documentation, writing guides, and providing examples. Since Flummox's core innovation is its approach to isomorphism, I would like to make it especially easy for newcomers to learn how to use Flummox to create isomorphic applications.\n\nFeature requests and PRs are absolutely welcome, as long as they keep with the spirit of a minimal core API. Any additional features (e.g. undo-redo & versioning) are likely to be implemented as addons, rather than as part of the core.\n\n\nRecommended libraries\n---------------------\n\nFlummox is just Flux. It has no opinion on the rest of your stack. You don't even have to be using React. But in case you're interested, here are some recommended tools and libraries that complement Flummox well:\n\n* [React (of course!)](http://facebook.github.io/react/)\n* [Immutable.js](http://facebook.github.io/immutable-js/) — Using immutable data in your applications not only makes your application more performant, but it also simplifies state management in your stores. No more defensive copying! It also helps ensure isolation between stores by reducing the likelihood that you'll accidentally mutate a dispatched payload.\n* [React Router](https://github.com/rackt/react-router) — A complete routing solution for React, with excellent support for isomorphic applications.\n* [Babel](https://babeljs.io/) — Use next-generation JavaScript (ES6, and even some ES7) today. Once you've tried it, it's the only way to write JavaScript. Babel also very conveniently supports JSX compilation.\n\n\nInspiration and thanks\n----------------------\n\n* Facebook, obviously.\n* Pete Hunt's talk at React.js Conf 2015 [\"Full Stack Flux\"](https://www.youtube.com/watch?v=KtmjkCuV-EU). The idea of stores as essentially \"a reduce() + a change event\" was illuminating.\n* [alt](https://github.com/goatslacker/alt), a similar Flux library from which I shamelessly copied (ideas, not code)\n\nLicense\n-------\n\nMIT\n\nAndrew Clark [@acdlite](https://twitter.com/acdlite)\n"}