Templates and getting started experience

[radu-matei]

I've been thinking a lot lately about using our templates to guide the user a bit more through the experience of 1) bootstrapping their application and 2) using Spin features.

More specifically, for 1):

• when I create an application based on a known, maintained template, I set the name, description, and path for my initial component, but then I have to look up what commands I need to build and run. We try to make that experience consistent across templates, so spin build and spin up should be enough, but a) that assumes the user knows those commands, and b) there are templates that require a one-off command be executed before you can even spin build (looking at you, npm install...).

• so to address this, I'm thinking we could extend the interactive spin new process with per-template prompts that could execute commands (if enabled) — like install dependencies, build, then immediately run the application for the first time.

For 2):

• once I have a starter app and I validated it runs (ideally helped by 1), immediately I need to open the docs to learn what I can do in my app. More than once I've wished for commented blocks in either spin.toml or the actual source code that gets generated for me.

The gist of this issue is: we have an idea what people tend to want to do once they generate an application -- first build and run it; then, they ask how to use certain features.

Can we streamline this experience more through our templates?

Happy to kickstart a SIP if this is a direction people would be interested in.

[ThorstenHans]

I like the idea of guiding new users through the process of running their app for the first time. Here are a couple of thoughts:

No 1:

• Ideally, required commands (e.g. spin build) show a description of what will happen next and ask the user to confirm it:

> Spin Apps are compiled down to WebAssembly... to do so, you can the `spin build` command. 
> Press [ENTER] to run `spin build` for the first time

• We should allow users to disable automatic command execution once the template has been rendered. IMO, this is especially important for experienced Spin developers, who want to bootstrap a new Spin App but don't have to build/run it immediately

No 2:

• I would love to see all available parameters of spin.toml as commented blocks
• For actual code, I wonder how we would balance between overwhelming the user with a massive amount of code illustrating all major features

Perhaps we could address code samples by adding a defined comment in the template source code and create a simple plugin for Spin which users could instruct splitting out sample code for a defined scenario (e.g. Using a kv store with Spin)

[radu-matei]

(clarifying, not suggesting we execute any command automatically without user input, but ask, whether it's standard spin build/up or template specific like npm install)

[lann]

We have something a bit along these lines in spin doctor: https://github.com/fermyon/spin/blob/967fdf368612478cef176bccc491faffad680050/crates/doctor/src/rustlang/target.rs#L145-L146

[itowlson]

Tool setup is a long wished for improvement! Unfortunately, from the spin doctor work and earlier investigation of doing tool setup from templates, I recall it got kinda hard to do tool detection and setup in a way that was wieldy and worked across OSes. (At one point I tried to add a way for templates to detect if their tool dependencies were installed - just Rust and the WASI target in the first instance - and foundered on "how do I even express this in a declarative way.") We may want initially to pare it back to "the template system knows the top 5 Wasm toolchains and how to install them" rather than "each template can express its own custom tool setup."

Also 100% agree with what Thorsten and Radu said about the trust implications of "running a template could execute arbitary programs on your machine." Anything we do in this area needs to be diligent about informing users and obtaining informed consent.

Press [ENTER] to run spin build for the first time

One thing to consider is "we will do this for you!" (press Enter to run spin build) vs "here is what to do" (now run spin up --build to build and run your application). The first is more helpful in the very short term, and of course shortens "time to success." The second gives the user experience of performing the task: for many people this helps learning more than being told what the computer is doing for them. I hope we can balance those factors (and either would be more than what we do now!).

I would love to see all available parameters of spin.toml as commented blocks ... For actual code, I wonder how we would balance between overwhelming the user with a massive amount of code illustrating all major features (Thorsten again!)

The current templates were, admittedly, a bit of a reaction against "create new project" systems that gave you a whole application where experienced users had to delete it all or new users had to struggle to see what was important. We (I) might well have erred too far in the opposite direction! But I'd definitely want us to think about the cognitive overhead of "what are all these things, do I need to understand all these comments."

But generally yes this is ripe for review, and we can always do more to help users get started!