Feathers: Create a comprehensive tutorial/example

[ekryski]

Our Todo example is great for simplicity but doesn't answer questions most people have when they come to feathers. The tutorial needs to be more comprehensive and should demonstrate:

• How do you authenticate
• How do you do authorization (ie. permissions)
• How do you sanitize data prior to it hitting a service
• How to do data serialization out (ie. remove passwords)
• How do you run multiple real time instances (ie. how do you scale?)
• How do you filter/namespace events

So with this in mind we are going to be creating a new, very simple real time chat app. There are a lot of reasons for this but the TL;DR is it will make more sense as a realistic example for a Feathers app.

This was actually a difficult decision because we don't want to create more work for ourselves than we need to but a Todo list with login, different user roles, multiple micro services running on different machines just doesn't really make sense. That's one of the issues with Meteor's Todo example. It shoe horns realistic requirements into an unrealistic situation.

So with that said building a chat app is great choice for these reasons:

• It immediately makes sense why it should be real time. Real time Todos are kind of a gimmick, real time chat is actually valuable.
• It makes sense to have login and different user roles
• We can separate it out into different services more naturally and it makes sense to scale certain ones more than others. For example, the message service will get way more traffic in a chat app than auth or user services.
• It will still be fairly simple to grasp
• It can showcase all that feathers offers (hooks, db adapters, real time, isomorphic)
• It can be expanded on for more advanced examples (picture/video chat, mobile apps, mail sending, etc)

Feathers Real Time Chat Tutorial Steps

These are the things the app/tutorial should cover, in this order:

Basic Intro

• [x] Brief intro to Feathers
  
  
  
  • What it is
  
  
  • Philosophy
  
  
• [x] Download Feathers
• [x] Generate a new app
• [x] Start the app (we should already have a Users service)
• [x] Set up/test out authentication
• [x] Generate additional Messages service
• [x] Introduce hooks and add authorization for the Users service
  
  
  
  • Admin roles (can delete/edit any messages)
  
  
  • Regular user roles (can send a message, can only edit their own messages)
  
  
• [x] Wire up the client side code
  

  Next Steps (Advanced Intro)

These might be a continuation of the actual guide or may be separate projects/blog posts. I don't feel that they need to be done for this issue to be complete so we'll probably move them to their own later.

• [ ] Adding social sign-on with Github and explaining how to consolidate accounts
• [ ] Adding email confirmation
• [ ] Adding direct messages (ie. name spacing events)
• [ ] Breaking out services into their own apps (ie. scaling)
  
  
  
  • Real time communication options (via db, via feathers client, via pub-sub/redis)
  
  
• [ ] Dockerizing your Feathers app
• [ ] Deploying to Digital Ocean
• [ ] Creating mobile clients

[r3wt]

my questions exactly. no information anywhere.

[daffl]

We do have documentation for most of those topics at http://feathersjs.com/learn/# and the respective plugin readme files we just want to organize it better. We could probably do a much better job with that if we knew what you are looking for.

[ahdinosaur]

targeted tutorials for each of those advanced features (if it doesn't already exist) would be awesome. :+1:

by the way, i've been working on enspiral-craftworks/business-stack which aims to be a comprehensive example of a full stack application using feathers, react, redux, tcomb, etc. still a work in progress, most relevant to feathers is that it prompted me to write feathers-action. :rabbit:

[ekryski]

@ahdinosaur Woot! We'll definitely link to those as examples. I'm going to update the description with what we have talked about as a core team for a good starter example.

Two things:

1. You'll probably want to update it to use feathers rather than feathers-client once we officially launch feathers 2.0 (or even before now that feathers is isomorphic)
2. Make sure you add feathers-plugin to your package.json keywords. Then we'll have it automatically load up on the new site.

[ekryski]

Just a guide for adding the client side piece and weeee're done.

[ekryski]

The main tutorial is done. The "extended" parts would be way to massive to fit into one guide. They'll each be their own guides that build on the original and will be tracked separately.

[ekryski]

I've created issues for all the remaining guides in the https://github.com/feathersjs/feathers-docs repo.

[kenzaburo]

Hi,

I just want to write somethings which I felt about Feathersjs.
I am PHP base web engineer. And now I want to change to Nodejs stack base. After looking around, then I choose Feathersjs a try. But after three days, I can say it is not easier than use nodejs+expressjs+seqelizejs + postgres.

The document is to short and simple, everything is packed, and there is no anyone write a comprehensive tutorial.

It looks like the document assumes people who want to use Feathersjs alreay know nodejs,expressjs,socketio...etc. So sad.

[marshallswain]

@kenzaburo It's impossible to not agree with you. Feathers is built on those technologies, and all of those, except Node.js, are interchangeable for something else. We support a huge variety of tech, which is one of the features that makes FeathersJS so useful. What most Feathers users find is that you're right, it's not easier to get started than nodejs+expressjs+sequelizejs+postgres, but once you have some experience using those technologies and you start building apps, Feathers brings them together in an architecture that will let you build massively huge applications in ways that other frameworks simply do not.

It looks like the document assumes people who want to use Feathersjs alreay know nodejs,expressjs,socketio...etc. So sad.

This just a reality of Open Source work, but it's also uniquely different for Feathers because of how many databases we support. We have chosen to write examples using databases that have a low overhead and learning curve (like NeDB, which has probably the lowest of all of them). We are just a few guys who build Feathers in our spare time, and our current documentation rewrite is taking a LOT longer than we hoped. But even when it's finished, it won't include how to get setup with every database that we support. The nice thing for new users in Node.js + ExpressJS + Sequelize + Postgres land is that each of those technologies has great communities with great documentation. Once you learn them, if we're still the best architecture around (which I'm guessing will be the case), jump back into Feathers and enjoy its benefits. In the meantime, we will see what we can do to make it more friendly for newcomers. Like I said, we have lots of new docs that we're wrapping up, including a terrific new guide by @eddyystop that I think will really help beginners.

Cheers.

[eddyystop]

Repo feathers-guides section Step by Step Intro to Feathers is a guided intro to using Feathers. It does still assume you have some familiarity with Node and Express.

There are literally hundreds of tutorials and videos available on those topics, with each doing a better job on their area of focus that we could do. There's a lot to learn and I don't see a way to avoid it.

Meteor tried to wrap up all these technologies and "hide" them away from their developers. They were able to write intros into the whole ecosystem with their large funding (something we don't have). Still, it appears they failed and are moving to something else. The "hiding" bit their devs eventually; rapidly changing technologies made their choices tired. A group of former Meteor developers are using Feathers now.

I think you will be disappointed if you are looking for a one stop learning experience for Node, Express, etc. It does not exist.

This ecosystem is a seemingly chaotic, sweltering pool of Darwinian evolution. Nothing is sacred. Node is even planning to be independant from Google's V8. Most masterpierces of products are significantly improved upon within the year. Express competing with koa and Hapi. The sacred socketio now dealing with uws. jQuery made irrelavent. Underscore blown away by lodash. Google's AngularJS being rocked by Facbook's React, both now staring down the barrel of Vue.

It takes time to learn the pieces, and it'll take time to stay current. The benefit is that the technology in this ecosystem improves by leaps and bound.

[letminin]

Great job !

[lock[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue with a link to this issue for related bugs.