The most complete React/Flux dev stack and starter kit for universal functional web apps. Forget about evil frameworks, learn laser focused libraries and patterns instead.
Techniques
- Universal JavaScript (formerly isomorphic), one dev stack for browser, server, desktop, mobile.
- Functional works: App state snapshots, time travel, hot reload everything.
- React with server side rendering on expressjs backend.
- Super minimal Flux with atomic immutable.js app state for fast rendering and sane state management.
- ECMAScript 2015+ with babeljs.io. JSX and Flowtype syntax supported. Sourcemaps are enabled by default.
- Well tuned webpack dev stack with handy notifier. TDD ready.
- Karma as the test runner, mocha as test framework, and Chai as BDD / TDD assertion library.
- Shallow rendering for testing React components without DOM.
- eslint ES6 linting with React JSX support. (Sublime Text 3 integration)
- Localization via formatjs.io, stale browsers supported as well.
- react-router for routing on client and server side.
- Simple yet powerfull sync/async validation based on famous chriso/validator.js
- Auth example with
requireAuth
higher order component to protect access to specific pages. - LESS, SASS, Stylus, or plain CSS with autoprefixer.
- Easy undo/redo and load/save for app state.
- Long Term Caching through file hashes enabled.
Prerequisites
Install node.js. Then install gulp.js.
npm install -g gulp
Windows
Use this if you are using JEST or another library, which has to be compiled.
- Install Python - Install version 2.7 of Python and add it to your path or/and create a PYTHONPATH environment variable.
- Install Visual Studio (Express Edition is fine) - We will need this for some of modules that are compiled when we are installing Este. Download VS Express, get one of the versions that has C++ - Express 2013 for Windows Desktop for example.
- Set Visual Studio Version Flags - We need to tell node-gyp (something that is used for compiling addons) what version of Visual Studio we want to compile with. You can do this either through an environment variable GYP_MSVS_VERSION. If you are using Express, you have to say GYP_MSVS_VERSION=2013e.
Thanks to Ryanlanciaux
Create App
git clone https://github.com/este/este.git este-app
cd este-app
npm install
Start Development
- run
gulp
- point your browser to localhost:8000
- build something beautiful
Dev Tasks
gulp
run app in development modegulp -p
run app in production modegulp test
run eslint, karma-ci, webpack build for productiongulp tdd
run app in dev mode with Karma configured for test driven development
CI Tasks
npm start
just run app, remember to set NODE_ENV=production and others environment variables.npm postinstall
just alias forgulp build --production
, useful for Heroku.npm test
just alias forgulp test
Documentation
So you decided to give a chance to this web stack, but where is documentation? Code is documentation itself as it illustrates various patterns, but for start you should read something about React.js. Then you should learn what is the Flux application architecture. Now refresh you JavaScript knowledge about "new" JavaScript - learn ES6. This stack uses immutable.js and class-less design for a good reason. Check this nice short video, wouldn't be possible with classic OOP classes everywhere approach. Functional programming is a next (current) big thing, read why. Express.js is used on the Node.js based server. Application is universal, so we can share code between browser, server, mobile, whatever easily. Congrats, you're Este.js expert level 1 now :-)
Este.js in one minute
Most of the app shouldn't surprise you, if you are acquainted with technologies described in Documentation. But here is how you can use our Flux implementation.
Creating an action
Add a method to the returned object of any action.js
file:
updateFavouriteTodo(newTodoValue) {
// Some validation.
if (!newTodoValue) {
// We can dispatch as many actions as we want, it's quite handy for complicated actions.
dispatch(actions.warnUser, 'Your favourite todo cannot be empty.');
}
// Dispatch the action and its payload.
dispatch(actions.updateFavouriteTodo, newTodoValue);
}
Updating a store with an action
Add a case
to the switch of the corresponding store:
case actions.updateFavouriteTodo: {
// The state before the action is a parameter of the store function.
// All we need to do is to modify the state to reflect the modifications of the store.
return state.set('favTodo', new Todo(payload));
}
Using an action from a component
The root app.react.js
component creates actions and passes then to its children.
// todos/index.react.js
render() {
const {actions} = this.props;
return (
<FavouriteTodo actions={actions.todos}/>
)
}
// todos/favouritetodo.react.js
export default class FavouriteTodo extends Component {
static propTypes = {
actions: React.PropTypes.object.isRequired
}
onEdit(newTodo) {
const {actions} = this.props;
// It's just a function. It can't be simpler.
actions.updateFavouriteTodo(newTodo);
}
}
Accessing data/state from a component
It works just like with the actions. app.react.js
has access to the whole state, and can pass it to its children. So just pass everything through props.
Links
- wiki: Recommended React Components
- wiki: Recommended Sublime Text 3 Packages
- twitter.com/estejs
- github.com/enaqx/awesome-react
Tips and Tricks
- To check app state, press
ctrl+shift+s
, then open console. - With global app state, we don't need IoC container so badly - SOLID: the next step is Functional. Still DI is relevant for some cases and then use Pure DI.
- Learn immutable.js, for example Seq. Very handy even for native arrays and objects. For example, get object values:
Seq(RoomType).toSet().toJS()
- Even though we can use
import {canUseDOM} from 'react/lib/ExecutionEnvironment'
to detect browser/server, don't do it since it's runtime value. Use webpack DefinePlugin to setprocess.env.IS_BROWSER
rather, because compilation removes dead code. - How to use Closure Tools, gist
- Recommended editors are sublimetext and atom.io (tips).
- When
gulp
command fails withNo gulpfile found
. Problem is with gulp version on your system. Simple fix: gulpjs/gulp-cli#27 (comment)
FAQ
Why does the CSS flicker when starting the app/refreshing it?
In dev mode, webpack loads all the style inline, which makes them hot reloadable. This behaviour disappears in production mode (gulp -p
).
Does Hapi/SailJS/Restify/Rails work with Este? Do you have any example app for this framework?
Yes it does. Este is agnostic of what you use in your backend and is completely decoupled from the API. It uses an Express app for server-side rendering, but you can use anything for your API. The only benefit that an Express API has is that it can simply be use()
by the main app, like any other middleware.
Redux?
What's the difference withRedux aims to be the framework to rule them all. It wants to be everything for everyone, while Este assumes being strongly opinionated, needing much less boilerplate to work. Moreover, while Redux (or many other implementation of the Flux pattern) are frameworks, Este tries to simply be the show a pattern and a set of best practices.
Is it possible use XXX library with Este?
Yes. Este makes little assumptions about your stack, and passing every bit of needed info through props. This is not a framework, nothing prevents you from picking the bits you're interested in.
Do you have any other example apps using Este?
Right now, there are little open sourced apps on the web (if you have any example, feel free to send a PR, or tip us on Gitter). You can have a look at the other repositories of the este organization. You might for instance find some interesting stuff in este-firebase.
Does it work with React Native?
Yes! Check the native repo.
Why Este is pure and why we have to pass data through props?
Pure means no side effects. Programming without side effects rocks. It allows us to hot reload everything and testing is much easier as well. When component renders only data passed through props, shouldComponentUpdate can be implemented only once per whole app. One can say it's verbose, but it isn't. It's explicit. And remember, we have to pass only data going to be rendered. Actions have access to app state.
Training
- learn-reactjs.com
- javascript-skoleni.cz
- DzejEs.cz - czech articles about Este
Notes
- Este.js dev stack works on OSX, Linux, and Windows. Feel free to report any issue.
- As a rule of thumb, Este.js supports all evergreen browsers plus last two pieces of IE.
- You can support Este.js development via Bitcoin - daniel.steigerwald.cz/#donate-estejs
Credit
made by Daniel Steigerwald, twitter.com/steida