/este

The most complete minimal dev stack / boilerplate for React & Redux universal web apps.

Primary LanguageJavaScriptMIT LicenseMIT

Este.js

Circle CI Join the chat at https://gitter.im/este/este Dependency Status Deploy

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.

Breaking: Come to discuss Este with us at reactive2015.com conference. The speaker line up is surprisingly good: Guillermo Rauch, Nikita Prokopov, James Long, Martin Konicek (Facebook React Native developer), Julia Gao and more.

At a glance

Este universe is organized into several folders, each of them contains its own package.json.

@este/universal

This is umbrella package to help you working with different targets. You should not install any dependencies here. The only dependencies that are included in that package are eslint and its parsers so it's easier to work with Atom/SublimeText.

This package contains several scripts that are here to help you with development, but since they are just wrappers to the underlaying web/ and native/ tasks, it's not required to use them. See Dev and CI tasks section.

@este/common

Este common is a package that contains Flux (Redux) implementation, actions, reducers and universal logic that works across all targets. You should not install any React-specific or target-specific dependencies here to make this package fully cross-platform.

@este/web

This package contains previous Este/web and comes with both client and server.

@este/native

This package contains previous Este/native and comes with React Native iOS & Android implementations.

Prerequisites

Install node.js (v4 is required).

If you are using different node versions on your machine, use nvm to manage them.

You may also need to upgrade npm to 3.x

npm install -g npm@3.x

Techniques

Installing

git clone https://github.com/este/este.git este-app
cd este-app
npm install

Start Development

  • run npm run web-start-dev
  • point your browser to localhost:8000
  • build something beautiful

Dev Tasks

  • npm run web-start-dev run app in development mode
  • npm run web-build build web package
  • npm test test native, web & common

Prod Tasks

  • npm run web-start just run app, remember to set NODE_ENV=production and others environment variables.

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 :-)

Links

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

Tips and Tricks

  • To check app state, just open browser 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. 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 set process.env.IS_BROWSER rather, because compilation removes dead code.
  • How to use Closure Tools, gist
  • Recommended editors are sublimetext and atom.io (tips).

FAQ

Why I am seeing warnings and errors when running npm install?

You can completely ignore them since they are coming from optional React Native dependencies as noted here. They will be gone with React Native 0.12 being released.

Why do I get EACCES error during npm install?

This indicates that you do not have permission to write to the directories that npm uses to store packages and commands. One possible solution is to change the permission to npm's default directory.

  1. Find the path to npm's directory: npm config get prefix For many systems, this will be /usr/local
  2. Change the owner of npm's directory's to the effective name of the current user
sudo chown -R `whoami` <directory>

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 (NODE_ENV=production npm web-start).

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.

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.

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

Notes

  • Este.js dev stack works on OSX, Linux, and Windows.
  • As a rule of thumb, Este.js supports all evergreen browsers plus last two pieces of IE.
  • Support Este.js development via Bitcoin - daniel.steigerwald.cz/#donate-estejs

Credit

Este.js

made by Daniel Steigerwald, twitter.com/steida, @grabbou and the community