Setting Up A New Project

[codepath]

Setting Up A New Project

[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 [email protected] 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
#5 (comment)
.

[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 [email protected]
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 [email protected]
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
#5 (comment)
.

[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 [email protected]
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
#5 (comment)
.

[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 [email protected]
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
#5 (comment)
.

[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 [email protected]
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
#5 (comment)
.

[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 [email protected] 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
#5 (comment)
.

[pixelknitter]

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

[CrabDude]

Imgur

On Tuesday, April 28, 2015, Edward Freeman [email protected] 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
#5 (comment)
.

[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 [email protected] wrote:

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

—
Reply to this email directly or view it on GitHub
#5 (comment)
.

[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.