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

[ryhinchey]

server side rendering should probably be its own section of the site and I think needs to have more detail than this at least providing explanation/answer for the following:

• hydration - Component hydration #34)
• state persistence - redux has a great section on ssr we can pull inspiration from https://redux.js.org/recipes/server-rendering
• using with express (or insert other popular node web framework here)

[dfabulich]

That would be nice, but I think it's beyond the scope of this PR.

[ryhinchey]

Yah for sure. Perhaps remove the entire section then? I don’t think the ssr story is ready fully ready and having it in the docs might create confusion/frustration for people looking to go that route right now.

[ryhinchey]

Does it make sense at this early of a stage to suggest an alternative to jsx? People coming from React are super familiar with jsx. We might want a separate section for alternatives to jsx in the future vs including it in the getting started instructions? You can get started easily with jsx now

[dfabulich]

Documenting HTM early on absolutely makes sense, IMO.

HTM is by far the easiest way to get started with React/Preact/Crank. For now, it's even easier than using @babel/standalone. (Though I hope this gets better when my babel PR lands. babel/babel#11466 )

In my experience, most people coming from React don't know how to set up JSX from scratch. They use create-react-app, or they let just one person on their team set it up for them once, typically with a complicated do-it-all build tool like Webpack.

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