Setting Up A New Project

[CrabDude]

• Glean all the fundamentals of getting a hello world express server up and running from the Setup wiki the prework and the week 1 assignment.
• Assume their environment is already setup

What success looks like: Succinctness and clarity. Less is more. Reference Wikis: Authentication & Authorization, Setup

Open separate issues for required links to community sources if you're having trouble finding any.

Please assign to yourself before working on this. /cc @NinjaSudo @philster @azoff @DiyahM

[pixelknitter]

@CrabDude I've compiled some good information for an in-depth (and concise) project setup, but I'm wondering if there's certain opinions we should express or avoid.

For instance, using https://github.com/steveukx/hogan-middleware versus hjs. Based upon the guidelines I'd imagine the use of generators is fine, starting with the default for express is a good start, no?

[CrabDude]

There're 3 guidelines.

1. Base recommendations of projects that have >80% coverage in the community (express, passport) or will eventually (es6 => babel, promises, async/await). Anything that falls into this category will be the default for code samples unless specifically teaching a subject that involves alternatives (like the Control-flow guide talking about callbacks and generators)
2. Recommending alternatives in name & link only when pertinent. (E.g., see the Prework's mention of express alternatives). Even in the Rendering guide, I think it's probably best to avoid code samples for alternative rendering engines because there are just so many. Likewise, short of having a specific guide for large alternatives like hapi, I think it's best to altogether avoid code samples for alternative frameworks as links to their documentation should typically suffice. While this is mostly gray, let's fair on the side of conciseness and focus with links to alternatives so as not to overwhelm.
3. Utility libraries or project choices. These are used for convenience, with no clear "best". Examples include bluebird, bluebird-nodeify, bcrypt, mongoose, etc... There are many alternative A+ compliant promise libraries, as there are many alternative ORMS, rendering engines, configuration tools or logging frameworks. There's no real rule on when to mention alternatives here per say, but with the node.js ecosystem being what it is with its explosion of diversity of packages, I try not to overwhelm.

So in answer to your question, yes, we assume express (>80%) and async/await (>80% eventually as an idiomatic language construct) and mention generators/bluebird.coroutine in name and link only, unless in the control-flow guide.

For Hogan, I would add a link in the project setup like the following: (See the [Rendering Guide](...) for a list of recommended rendering engines) and then in the Rendering Guide have a section toward the bottom with a list of links to rendering engines (can be sorted by popularity) an a max 1 sentence description.

Cheers, Adam

On Monday, April 27, 2015, Edward Freeman notifications@github.com wrote:

@CrabDude https://github.com/CrabDude I've compiled some good information for an in-depth (and concise) project setup, but I'm wondering if there's certain opinions we should express or avoid.

For instance, using https://github.com/steveukx/hogan-middleware versus hjs. Based upon the guidelines I'd imagine the use of generators is fine, starting with the default for express is a good start, no?

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-96755703 .

[CrabDude]

I added a more concise version of the above to the "Contributing Guidelines" Guide https://github.com/codepath/nodejs_guides/wiki/Contributing-Guidelines#code-samples--package-recommendations .

Cheers, Adam

On Mon, Apr 27, 2015 at 11:51 AM, Adam Crabtree adam@thecodepath.com wrote:

There're 3 guidelines.

1. Base recommendations of projects that have >80% coverage in the community (express, passport) or will eventually (es6 => babel, promises, async/await). Anything that falls into this category will be the default for code samples unless specifically teaching a subject that involves alternatives (like the Control-flow guide talking about callbacks and generators)
2. Recommending alternatives in name & link only when pertinent. (E.g., see the Prework's mention of express alternatives). Even in the Rendering guide, I think it's probably best to avoid code samples for alternative rendering engines because there are just so many. Likewise, short of having a specific guide for large alternatives like hapi, I think it's best to altogether avoid code samples for alternative frameworks as links to their documentation should typically suffice. While this is mostly gray, let's fair on the side of conciseness and focus with links to alternatives so as not to overwhelm.
3. Utility libraries or project choices. These are used for convenience, with no clear "best". Examples include bluebird, bluebird-nodeify, bcrypt, mongoose, etc... There are many alternative A+ compliant promise libraries, as there are many alternative ORMS, rendering engines, configuration tools or logging frameworks. There's no real rule on when to mention alternatives here per say, but with the node.js ecosystem being what it is with its explosion of diversity of packages, I try not to overwhelm.

So in answer to your question, yes, we assume express (>80%) and async/await (>80% eventually as an idiomatic language construct) and mention generators/bluebird.coroutine in name and link only, unless in the control-flow guide.

For Hogan, I would add a link in the project setup like the following: (See the [Rendering Guide](...) for a list of recommended rendering engines) and then in the Rendering Guide have a section toward the bottom with a list of links to rendering engines (can be sorted by popularity) an a max 1 sentence description.

Cheers, Adam

On Monday, April 27, 2015, Edward Freeman notifications@github.com wrote:

@CrabDude https://github.com/CrabDude I've compiled some good information for an in-depth (and concise) project setup, but I'm wondering if there's certain opinions we should express or avoid.

For instance, using https://github.com/steveukx/hogan-middleware versus hjs. Based upon the guidelines I'd imagine the use of generators is fine, starting with the default for express is a good start, no?

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-96755703 .

[pixelknitter]

Thanks Adam, that clears things up a bit for me. Also makes sense, I was thinking that some of the content I was putting together might be better off splitting into a new guide with more completeness and a reference to it in this guide as a "Further Reading" or "Next Step".

[CrabDude]

What did you have in mind to put in there ("Further Reading" or "Next Step")?

[pixelknitter]

Current Headers

• Overview
• Generate Your Project
• Create Hello World
• Improving Your Project Environment
• Next Steps

(more a reference to other guides)

1. View Rendering Engines
2. Create Your First Test
3. Debugging

[pixelknitter]

Right now, I'm using the express generator for simplicity and to save time. Then explaining what gets created. Though the Express generator docs does some of this.

[CrabDude]

Sounds good. The express generator is good. It's very common and doesn't require getting into the nitty gritty of yoeman, and generators.

On Mon, Apr 27, 2015 at 5:01 PM, Edward Freeman notifications@github.com wrote:

Right now, I'm using the express generator for simplicity and to save time. Then explaining what gets created. Though the Express generator docs does some of this.

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-96853927 .

[pixelknitter]

Haha, yeah, I wasn't gonna start off with yoeman. That definitely gets a bit gritty. :)

[pixelknitter]

@CrabDude finishing up with this one. Had a little hiccup once I went through and realized that I would need to introduce routes (briefly) with the generator. Good to start splitting things up but makes it little heavier. Need to spend some time rehashing the flow. Hope to have it done by tomorrow morning at the latest.

[CrabDude]

Excellent. Thanks for the update.

On Mon, Apr 27, 2015 at 9:48 PM, Edward Freeman notifications@github.com wrote:

@CrabDude https://github.com/CrabDude finishing up with this one. Had a little hiccup once I went through and realized that I would need to introduce routes (briefly) with the generator. Good to start splitting things up but makes it little heavier. Need to spend some time rehashing the flow. Hope to have it done by tomorrow morning at the latest.

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-96907383 .

[pixelknitter]

@CrabDude Want me to post it a little early with some TODOs so you can give feedback now? Or wait until I get a first draft that's complete?

[CrabDude]

Tomorrow's fine.

On Mon, Apr 27, 2015 at 9:49 PM, Edward Freeman notifications@github.com wrote:

Want me to post it a little early so you can give feedback now? Or wait until I get a first draft that's complete? I can always TODO the section I have finished.

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-96907467 .

[pixelknitter]

@CrabDude I've posted v1 of the guide here: https://github.com/codepath/nodejs_guides/wiki/New-Express-Project

Let me know if you have any suggestions.

[CrabDude]

Will do.

On Tuesday, April 28, 2015, Edward Freeman notifications@github.com wrote:

@CrabDude https://github.com/CrabDude I've posted v1 of the guide here: https://github.com/codepath/nodejs_guides/wiki/New-Express-Project

Let me know if you have any suggestions.

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-97102499 .

[pixelknitter]

@CrabDude Where can I put an image of the Hello World result?

[CrabDude]

Imgur

On Tuesday, April 28, 2015, Edward Freeman notifications@github.com wrote:

@CrabDude https://github.com/CrabDude Where can I put an image of the Hello World result?

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-97104342 .

[pixelknitter]

@CrabDude any feedback? Want to make sure I'm using the right format and such before I head into a second one.

[CrabDude]

Sorry, will get to this this weekend.

On Friday, May 1, 2015, Edward Freeman notifications@github.com wrote:

@CrabDude https://github.com/CrabDude any feedback?

— Reply to this email directly or view it on GitHub https://github.com/codepath/nodejs_guides/issues/5#issuecomment-98291147 .

[pixelknitter]

No worries! :)

[CrabDude]

Looks good. Can you:

1. Update all the code samples to use the corresponding syntax highlighting (node, bash, javascript (for JSON to allow comments)):

```node

\```

1. The default generator renders "Hello Express" not "Hello World", could you confirm and update the image accordingly.
2. It also does not have an index.js but app.js instead
3. The hello world route should be added somewhere in routes/, not app.js
4. Provide a small blurb about the difference b/w bin/www and app.js

Thanks. Sorry for taking so long to get around to looking at this. Will update with more after the above is complete.

[pixelknitter]

@CrabDude thanks for the feedback. I noticed you made some changes to the references, the links throughout the guide however got broken. Want me to fix those as well?

[pixelknitter]

fixed the links.

[pixelknitter]

@CrabDude I have a few thoughts on 2-4:

1. got it
2. "Hello Express" is the default, I intended to have them change that. Do you think that's too much depth? Under the "Create Hello World" section I've modified it perhaps to make it more clear.
3. The generator actually creates both index.js and app.js (the index.js is within the /routes/ directory).
4. I've modified the "Create Hello World" section to explicitly call out that we're now working in the /routes/ directory.

[pixelknitter]

Review the latest and let me know what you think. Specifically the following sections:

1. Create Hello World
2. Configuration Scripts

Everything else were minor fixes to the broken links.

[CrabDude]

LGTM. Thanks.