Suggestion: include a little more code in the "hz init" skeleton

[snickell]

The horizon "getting started" docs are solid, but it'd be nice to get started by just running "hz init" and looking around.

Maybe it could be nice to include a few basic client/server bits in the skeleton created by "hz init" (e.g. a basic "add an item to the list" form, the associated server-side collection, and a query) would make getting started more fun for those of us who like to just "jump in".

Personally, I often find this extra-skeleton helpful even after I've worked with a framework in another project. The first few times creating a new project from scratch using a particular framework it can be nice to have a few reminders "oh yeah, you just put X here and do Y....".

[snickell]

Anecdotally, 40 minutes after thinking "Time to go play with Horizon! This is really exciting!", I still don't have a working client/server/collection app.

1. Getting horizon installed and rethinkdb was easy (other than a hiccup with a dash in the project name)
2. The "hz init" example app didn't include any ideas about where I'd go next to get a collection going.
3. I couldn't immediately figure out where to "paste the code" listed in the "getting started".
4. Finally thought to check the horizon github repo for examples, which don't include .hz directories so "hz serve" doesn't work in them.
5. Finally guessed at copying the files from examples/react-chat/dist to the directory I created with hz init/dist. Got a runtime error, probably need to set permissions?

[snickell]

See PR #406 which makes one of the examples (react-chat-app) easy to run with step by step instructions.

[deontologician]

We should really integrate the examples into the client, but I think hz init is outputting about what we want it to at the moment. Very minimal stuff, not a boilerplate generator. There's definitely a use-case for making it easy to get started with some more fleshed out examples though. We've been thinking of beefing up the index.html to link to examples and docs.

As far as this issue goes, @snickell what do you think a concrete proposal would be to make it easy to decide whether this ticket should be considered "fixed"?

[snickell]

Proposal 1a: implement hz init --example (or maybe --skeleton, --boilerplate, --todo, or....?) which generates a basic client/server example app. In the getting started doc, include this flag on the default suggested command.

Proposal 1b: hz init --example EXAMPLE_NAME to create one of several stock examples, and hz init --list to list available examples. Because of the "don't want to include config.toml but need to set things before things can be served" issue, the init command can get around this by setting default keys, and maybe enabling auto_create_tables. Its worth noting that 1b is the meteor approach and for all its flaws, the "getting started" ramp on meteor is one of the framework's aspects that has worked really well.

Proposal 2: link index.html to a one-click zip-file that is completely ready to "hz serve" (no need to update config.toml, generate tables, etc)

[marshall007]

@snickell I had a similar idea in #115 (comment). Basically I was thinking hz init <app> --framework=<generator> would shell out and run a scaffolding generator for the specified framework.

[mglukhovsky]

I'm a fan of option 1b, and potentially --framework <generator>.

I think that having at least one stock app that is easy to spin up from the hz tool would dramatically ease the learning curve for new users.

[mglukhovsky]

We should consider integrating with Yeoman and encourage people to provide Generators for common environments.

[deontologician]

Closing in favor of #583