Getting Started first impressions / suggestions

[davestewart]

Hi Rich,

It took me longer than I would have liked to get started with the starter project, because of a few reasons.

Problems

Starter project

1. The rollup project doesn't have hot reloading out of the gates
   • getting started you want as little friction as possible
   • I love rollup and use it in a few projects, but I wanted to concentrate on Svelte not tooling and get going
   • as such, I had to delete the original repo, and rewrite the terminal command to create a new repo, change into it, npm install, npm run dev, etc...
2. It took me a while to figure out how to add a nested component
   • I was confused about main.js role
   • I thought as App.html had no JS that perhaps main.js was it
   • This was compounded by the fact I thought it was importing App.html as its template
   • That then lead me to the false understanding that I should put my component tag in index.html
   • all this is of course wrong, and I eventually figured out that I needed to add a script body to App.html and the tag in the html

So I think that a nested component is the baseline for a "getting started project" - otherwise it's just an app skeleton. 100% of apps in the real world would have at least one nested component.

Ideally, a few other things would included as well, just to allow a first time user to prod and poke and see what happens when they change code, how it breaks, what feels intuitive, etc, etc.

Right now, here's nothing to play with, no "way in" as a hacker.

I know there is the REPL and it could be easy to copy/paste code, but TBH, the REPL once I got further than just clicking through the examples had some confusing issues...

REPL

1. The Hello world example provides more questions than answers

   • there's no script tag, so where is the data coming from!?
   • investigating further, it looks like the panel on the bottom right is the data
   • but HOW is the data being applied to the component? Props? Injection? I haven't written any of this! What's happening!!!?
   • Upon downloading the zip then you can see how it is done - looks like (in Vue terms of passing in options; I assume these are merged?)
   • as such, the REPL is limited in its value for those on "page 1" learning and more "what's possible"

2. What are the three panels?

   • this was answered in the previous point
   • the bottom right one appears to be "App" data only?
   • changing the text in this panel doesn't update the app, confusingly
   • however, changing the script THEN updates the app with the changed data

3. How to add data to the components?

   • so if:
     • the bottom panel is providing app data
     • the injection is handled for us
     • how do we use data in the app, in the REPL ?
   • turns out there's rules around this:
     • if the panel has data, i.e. is not {} it uses that
     • otherwise, you can use data () { } in the script body

Suggestions

Some suggestions here:

Project

• Have HMR in the Rollup starter project. If not, mention this from the get go.
• Have more functionality in the starter project, so we can hack
  • nested component
  • template syntax
  • data
  • props
  • binding
  • ui binding

I'm really sure you could do this with just a couple of components and it would not be overwhelming, rather exciting and hackable!

REPL

• update the html when data changes
• add a label to output and data panels so they are clear
• potentially move data to a tab before "app.html" so it seems more relevant
• potentially get rid of the data panel and just add it to a script / component body
• have some instructions which provide more information on how the REPL works, specifically with how it adds data to the component

Tutorial

Have a separate "Getting Started" page, without any of the complication of the guide.

• Installation
• Build
• Folders
• Creating the same starter project as mentioned above
• Step by step approach
• Adding complexity as you go

Having the getting started in the guide feels like it is "poked in" and the section skips over the detail you need for the sake of brevity - which is not what you need..

All this would make it much clearer the relationship between things, and how to add complexity.

I hope that's useful feedback from a first-time svelter.

[davestewart]

Ah, I see that some of the REPL issues these are being addressed in v3!

• https://v3.svelte.technology/repl

[davestewart]

That being said, some suggestions:

• put props above output so the flow is more intuitive (or make it its own tab)
• make each props instance an editor so you can use tab and get code errors

I just dragged some nodes around in the dev tools and got this which I think is nicer: