Provide detailed Getting Started instructions, with alternatives

[dfabulich]

Document how to get started with Crank and JSX with no build tool (using babel standalone), or how to set up JSX properly with Babel and Parcel (in HTML and in Node), or how to skip JSX entirely and use HTM.

[dfabulich]

The installation guide is now so long, it might make sense to split it into two pages, "Installation" and "Key Examples."

[brainkim]

Pulling this down and checking it out! The one thing I worry about is front-loading too much information about the almost infinite solutions out there for getting JSX to work in the browser. I really value putting examples first and foremost, because that’s how people learn and not everyone who comes across the site is speaking English.

[dfabulich]

What if instead of a "Getting Started" page, there was an "Installation" page, and then separately a "Learn by Example" page? All of the examples would move to the "Learn by Example" page, and that would give the Installation page room to breathe?

FWIW, I do think this is roughly the right amount of information; more importantly, the reader can stop at any section and get a satisfying experience.

1. If you just want a taste of Crank in your browser, the first section is enough.
2. If you want to do it the "right way for production," the next section explains how to set up Babel and Parcel, and there's even a CodeSandbox available for you to check your work.
3. Still here? Here's the (surprisingly different!) installation instructions for SSR in Node
4. Finally, Crank is built around JSX, but you can use HTM instead if you prefer.

[PatrickDesign]

Nice writeup @dfabulich

[brainkim]

Some thoughts:

1. I don’t think we should have any solutions where we compile JSX stuff directly in the browser.
2. I am really attached to the getting started guide as it currently is, and would much rather have the detailed instructions on a separate page. I think this because build tooling is a moving target, and we might all be writing with Rome in 2021, who knows? Having the nitty-gritty details is important but I like how quickly we get the key examples.
3. Related, but any change in getting-started is mirrored in the root README of this repository. I do this by copying and pasting the markdown manually, and can do this myself, just something to keep in mind.
4. I’m starting to agree that a transpile-less option would be incredibly nice, I’m just not 100% on htm yet. Mostly, I’m just a little wary of the component closing tag syntax. Probably just me being silly. Have you checked out https://github.com/esxjs/esx too? Curious to hear your thoughts on which of the two is better.

[dfabulich]

#1 is surprising to me. In-browser Babel is React’s first intro to JSX; that makes perfect sense to me. https://reactjs.org/docs/add-react-to-a-website.html

#2 I’m not sure how far my current draft is from what you’d prefer. It sounds like a long installation page is at least acceptable, if not desirable. Currently I’ve got two pages, “Installation” and “Learn by Example.” Would you prefer to put the “Learn by Example” page first? (And call it “Getting Started?”)

#4 I like the little closing tag! I wish HTML had it.

But I do see that the opening tag is clunky. For self-closing tags with an ellipsis spread operator and a few properties matching variables in scope, I noticed it was easier to use h than HTM.

<${Button} ...${{foo, bar}} />
${h(Button, {foo, bar})}

As for ESX, I see that it addresses the opening tag problem, but I worry that it’s too easy to forget to register components, and that typos in component names don’t show up until runtime. In HTM, if I type htm<${Buttno} /> even my text editor can natively flag that as a syntax error. ESX can detect errors at compile time, but compilation is optional, so I might have to wait until runtime to catch errors.

[brainkim]

1 is surprising to me. In-browser Babel is React’s first intro to JSX; that makes perfect sense to me. https://reactjs.org/docs/add-react-to-a-website.html

Yes but I’m bemused by how every such guide says you shouldn’t do it in production. I get that we want people to get started quickly, but I suspect that the way to do it is to get them to a playground site, not tell them to do something which should never be done in prod.

2 I’m not sure how far my current draft is from what you’d prefer. It sounds like a long installation page is at least acceptable, if not desirable. Currently I’ve got two pages, “Installation” and “Learn by Example.” Would you prefer to put the “Learn by Example” page first? (And call it “Getting Started?”)

Most of your guide could be used. I’m just saying we could link out from getting-started to a page called Detailed Setup Instructions or something to sandbox the actual complexity of build systems within the docs to a single guide.

I agree completely with all your points about htm/esx.

[dfabulich]

I started taking a crack at putting "brief" setup instructions in the "Getting Started" guide with "detailed" instructions elsewhere, but I struggled to think of anything useful to say there other than:

## Installation
Crank is available on [NPM](https://npmjs.org/@bikeshaving/crank) in the ESModule
and CommonJS formats.

    ```shell
    $ npm install @bikeshaving/crank
    ```

Next you'll want to set up JSX and a module bundler.
We have a [detailed installation guide](/guides/installation) that should help. 

**The rest of this page assumes you have set up JSX and a module bundler.**

But that doesn't feel like it's really in keeping with what you wanted. This isn't "brief installation instructions," this is just linking to the real setup guide from the top of "Getting Started."

For installation options, I've enumerated three approaches:

• babel-standalone (brief, not appropriate for production)
• Parcel (long)
• htm (brief, but it's not as beautiful as JSX; none of the code examples are in HTM)

What's missing is a brief installation option that's suitable for production. The more I think about it, the only way to get that would be to implement a create-crank-app project, which I've filed as #94.