YO – LET’S SCAFFOLD A WEB APP WITH YEOMAN


By Mehdy Dara

Allo! Allo! In this 25-minutes codelab, you will build a fully functional web application from scratch with the help of Yeoman and FountainJS. The sample app will be written in ReactAngular2 or Angular1.

Don’t know any React or Angular? That’s okay, we’ll walk you through it. However, we do assume that you have some previous JavaScript experience.

Build this sample app with Yeoman

The sample web app you’ll build today will be a implementation of TodoMVC. You will be able to add todos, delete todos, filter todos, and together we’ll add a feature to save todos offline.

Finished TodoMVC app

What’s in this codelab?

We will build the above TodoMVC app from scratch. Each step builds on the previous so go through each step one by one.

It will take approximately 25 minutes to complete this codelab. By the end, you’ll have a snazzy TodoMVC app and your computer will be set up to build even more awesome web apps in the future.

Let’s get started with Step 1 »

Most of your interactions with Yeoman will be through the command line. Run commands in the Terminal app if you’re on Mac, your shell in Linux, or cmder (preferably) / PowerShell / cmd.exe if you are on Windows.

Install prerequisites

Before installing the Fountain Webapp Generator, you will need the following:

  • Node.js 6 or higher
  • npm 3 or higher (which comes bundled with Node)
  • Git

You can check if you have Node and npm installed by typing:

node --version && npm --version

If you need to upgrade or install Node, the easiest way is to use an installer for your platform. Download the .msi for Windows or .pkg for Mac from the NodeJS website.

The npm package manager is bundled with Node, although you might need to update it. Some Node versions ship with rather old versions of npm. You can update npm using this command:

npm install --global npm@latest

You can check if you have Git installed by typing:

git --version

If you don’t have Git, grab the installers from the git website.

Install the Yeoman toolset

Once you’ve got Node installed, install the Yeoman toolset:

npm install --global yo

Errors?

If you see permission or access errors, such as EPERM or EACCESS, do not use sudo as a work-around. You can consult this guide for a more robust solution.

Confirm installation

It is a good idea to check that everything is installed as expected by running commonly used Yeoman commands like yo with the --version flag as follows:

yo --version

Versions of the CLI tools that this codelab works with

Technology changes quickly! This tutorial has been tested with yo 1.8.4. If you are running into issues with a newer version, we would like to hear about it. Please open up an issue on our tracker.

In a traditional web development workflow, you would need to spend a lot of time setting up boilerplate code for your webapp, downloading dependencies, and manually creating your web folder structure. Yeoman generators to the rescue! Let’s install a generator for FountainJS projects.

Install a generator

You can install Yeoman generators using the npm command and there are over 3500+ generators now available, many of which have been written by the open-source community.

Install generator-fountain-webapp using this command:

npm install --global generator-fountain-webapp

This will start to install the Node packages required for the generator.

Errors?

If you see permission or access errors, such as EPERM or EACCESS, do not use sudo as a work-around. You can consult this guide for a more robust solution.


Along with using npm install directly, you can search for generators via the Yeoman interactive menu. Run yo and select Install a generator to search for published generators.

« Return to overview or Go to the next step »

We’ve used the word “scaffold” a few times but you might not know what that means. Scaffolding, in the Yeoman sense of the word, means generating files for your web app based on your specific configuration requests. In this step, you’ll see how Yeoman can generate files specifically for your favorite library or framework — with options for using other external libraries like Webpack, Babel and SASS — with minimal effort.

Create a project folder

Create a mytodo folder for all your codelab work:

mkdir mytodo && cd mytodo

This folder is where the generator will place your scaffolded project files.

Access generators via the Yeoman menu

Run yo again to see your generators:

yo

If you have a few generators installed, you’ll be able to interactively choose from them. Highlight Fountain Webapp. Hit enter to run the generator.

Use generators directly

As you become more familiar with yo, you can run generators directly without the use of the interactive menu, like so:

yo fountain-webapp

Configure your generator

Some generators will also provide optional settings to customize your app with common developer libraries to speed up the initial setup of your development environment.

The FountainJS generator provides some choices to use your favorite:

For this codelab, we will use ReactWebpackBabelSASS and the Redux TodoMVC sample.

Select successively these options with the arrows keys and the enter and watch the magic happen.

Yeoman will automatically scaffold out your app, grab your dependencies. After a few minutes we should be ready to go onto the next step.

« Return to overview or Go to the next step »

Open up your mytodo directory to take a look at what was actually scaffolded. It’ll look like this:

In mytodo, we have:

src: a parent directory for our web application

  • app: our React + Redux code
  • index.html: the base html file
  • index.js: the entry point for our TodoMVC app

conf: a parent directory for our configuration files for third-party tools (Browsersync, Webpack, Gulp, Karma)

gulp_tasks and gulpfile.js: our builder tasks

.babelrcpackage.json, and node_modules: configuration and dependencies required

.gitattributes and .gitignore: configuration for git

Create the first commit

After generation and installation you should have a fresh git repository already initialzing.

You can safely add a commit to save the current state by these commands.

git add --all && git commit -m 'First commit'

« Return to overview or Go to the next step »

To preview your web app in your favourite web browser, you don’t have to do anything special to set up a local web server on your computer — it’s part of Yeoman.

Start the server

Run a npm script to create a local, Node-based http server on localhost:3000 (or 127.0.0.1:3000 for some configurations) by typing:

npm run serve

Open a new tab in your web browser on localhost:3000:

Stop the server

If you ever need to stop the server, use the Ctrl+C keyboard command to quit your current CLI process.

Note: You can’t have more than one http server running on the same port (default 3000).

Watch your files

Open up your favorite text editor and start making changes. Each save will automatically force a browser refresh so you don’t have to do this yourself. This is called live reloading and it’s a nice way of getting a real-time view of your application state.

Live reloading is made available to your application through a set of Gulp tasks configured in gulpfile.js and Browsersync configured in gulp_tasks/browsersync.js; it watches for changes to your files and automatically reloads them if it detects a change.

Below, we edited Header.js in the src/app/components directory. Thanks to live reload we go from this:

To this instantly:

Don’t forget the test!

You have a TodoMVC app tested and you change the title header. You should edit test in `mytodo/src/app/components/Header.spec.js` **or** revert the change for demonstrate livereloading

For those unfamiliar with Karma, it is a JavaScript test runner that is test framework agnostic. The fountainjs generator has included test framework Jasmine. When we ran yo fountain-webapp earlier in this codelab the generator scaffolded files with pattern *.spec.js in the source folder of the mytodo folder, created a conf/karma.conf.js file, and pulled in the Node modules for Karma. We’ll be editing a Jasmine script to describe our tests soon but let’s see how we can run tests first.

Run unit tests

Let’s go back to the command line and kill our local server using Ctrl+C. There is already a npm script scaffolded out in our package.json for running tests. It can be run as follows:

npm test

Every tests should pass.

Update unit tests

You’ll find unit tests scaffolded in the src folder, so open up src/app/reducers/todos.spec.js. This is the unit test for your Todos reducer. For example we get focus on the first test who verify the initial state. (Note: on windows, you might need to add 127.0.0.1 localhost to your etc/hosts file)

it('should handle initial state', () => {
  expect(todos(undefined, {})).toEqual([
    {
      text: 'Use Redux',
      completed: false,
      id: 0
    }
  ]);
});

And replace that test with the following:

it('should handle initial state', () => {
  expect(todos(undefined, {})).toEqual([
    {
      text: 'Use Yeoman', // <=== HERE
      completed: false,
      id: 0
    }
  ]);
});

Re-running our tests with npm test should see our tests now failing.

If you want run test automatically on change you can use npm run test:auto instead.

Open src/app/reducers/todos.js.

Replace the initial state by:

const initialState = [
  {
    text: 'Use Yeoman',
    completed: false,
    id: 0
  }
];

Fantastic, you have fixed the test:

Writing unit tests make it easier to catch bugs as your app gets bigger and when more developers join your team. The scaffolding feature of Yeoman makes writing unit tests easier so no excuse for not writing your own tests! 😉

« Return to overview or Go to the next step »

Install npm package

To easily achieve this, we can use another Redux module called “redux-localstorage” that will allow us to quickly implement local storage.

Run the following command:

npm install --save redux-localstorage@rc

Use redux-localstorage

The Redux store should be configured to use storage. Replace the whole your src/app/store/configureStore.js by this code:

import {compose, createStore} from 'redux';
import rootReducer from '../reducers';

import persistState, {mergePersistedState} from 'redux-localstorage';
import adapter from 'redux-localstorage/lib/adapters/localStorage';

export default function configureStore(initialState) {
  const reducer = compose(
    mergePersistedState()
  )(rootReducer, initialState);

  const storage = adapter(window.localStorage);

  const createPersistentStore = compose(
    persistState(storage, 'state')
  )(createStore);

  const store = createPersistentStore(reducer);
  if (module.hot) {
    // Enable Webpack hot module replacement for reducers
    module.hot.accept('../reducers', () => {
      const nextReducer = require('../reducers').default;
      store.replaceReducer(nextReducer);
    });
  }

  return store;
}

If you look at your app in the browser, you’ll see that there are one item “Use Yeoman” in the todo list. The app is initialising the todos store if local storage is empty and we haven’t given it any todo items yet.

Go ahead and add a few items to the list:

Now when we refresh our browser the items persist. Hooray!

We can confirm whether our data is being persisted to local storage by checking the Resources panel in Chrome DevTools and selecting Local Storage from the lefthand side:

Write unit tests

For an extra challenge, revisit unit testing in Step 6 and consider how you might update your tests now that the code is using local storage.

« Return to overview or Go to the next step »

Ready to show your beautiful todo app to the world? Let’s try to build a production-ready version of it which we can ship.

Optimize files for production

To create a production version of our application, we’ll want to:

  • lint our code,
  • concatenate and minify our scripts and styles to save on those network requests,
  • compile the output of any preprocessors we’re using, and
  • generally make our application really lean.

Phew! Amazingly we can achieve all of this just by running:

npm run build

Your lean, production-ready application is now available in a dist folder in the root of your mytodo project. These are the files that you can put on your server using FTP or any other deployment service.

Build and preview the production-ready app

Want to preview your production app locally? That’s just another simple npm script:

npm run serve:dist

It will build your project and launch a local web server. Yo Hero!

« Return to overview or You’re done! Keep going »

Like what you see? Yeoman can do more.

Yeoman supports scaffolding out a lot more for Angular and other frameworks than what we’ve shown today.

For example, the Fountain Angular generator also supports creating new pipes, directives, services and components for you. A new components can be scaffolded by running yo fountain-angular2:component componentName, which will create your component file but also add a new componentName.spec.js for your unit test.

Find more sub-generators

To find out all the sub-generators for installed Yeoman generators, you can use yo --generators:

Where to go next

  • Yeoman is always evolving. Be sure to check out yeoman.io for more information and follow @yeoman and +Yeoman to stay up to date.
  • Fountain generators (github.com/FountainJS) helped us write this Todo app quickly and with elegance. Follow @YeomanFountain to stay up to date on new features and new releases.
  • React (facebook.github.io/react) a javascript library for building user interfaces.
  • Angular2 (angular.io) a framework to develop across all platforms.
  • Webpack (webpack.github.io) a module bundler who takes modules with dependencies and generates static assets representing those modules.
  • JSPM (jspm.io) a frictionless browser package management. Load any module format (ES6, AMD, CommonJS and globals) directly from any registry such as npm and GitHub with flat versioned dependency management.

That’s it from your man-in-a-hat for now. Thanks!

« Return to overview

Um comentário em “YO – LET’S SCAFFOLD A WEB APP WITH YEOMAN

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair /  Alterar )

Foto do Google

Você está comentando utilizando sua conta Google. Sair /  Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair /  Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair /  Alterar )

Conectando a %s