Add `--template` flag to `init` command

[f-f]

As mentioned in this comment on Discourse it would be really nice if Spago could have templates.

Examples from the post for how this could look like:

spago init --template halogen
spago init --template react-basic-hooks
spago init --template cli
... etc.

Opening this issue to track this, I don't have an opinion on how this should be implemented, but looking at previous art (e.g. Stack templates), I feel we could:

• have each template as a git submodule in the templates folder
• ..and include all templates in the binary (this is so that you can still make a project if you're offline)
• ..and optionally try to fetch them if we are online and they have been updated

[JordanMartinez]

Just a "way out there" question. How would this work if a project could be implemented by multiple backends? For example, the cli one. I see a few options:

1. Specify the backend in the template name (e.g. cli-js, cli-go, cli-c)
2. Use a separate flag to indicate the backend (e.g. --template cli --template-backend js)
3. Specify the backed in the template flag itself (e.g. --template-js cli vs --template-go cli)

I think first option makes the most sense.

[milesfrain]

Is spago the right tool for managing templates, especially with multiple backends?

I've had such a great experience with spago init, that --template seemed like a natural extension.

But after reading "Why can't spago also install my npm dependencies?", it seems like spago should be a dependency of the templates (rather than the templates being a dependency of spago).

So instead of:

spago init --template <template-name>@<template-version>

we could just suggest:

git clone --depth 1 --branch <template-version-tag> <template-url>

Starting with the clone approach is a low-barrier way to start deciding how we want to organize these templates and what the template guidelines should be. We could always feed this listing into the --template strategy later with minimal throwaway work.

Curating an initial list of templates seems outside the scope of this spago task though. I'm wondering where this effort should be tracked. Considering making another Discourse thread, or working on a page in documentation repo where we can start building a table of templates.

[JordanMartinez]

I agree with @milesfrain. This feels more like a documentation issue (i.e. "What are various starter/template projects that I can use to get started on X app?") than a feature that Spago should support as it avoids a number of issues.

To make this even simpler, one could instruct everyone to tag such repos with a purescript-template-project tag on GitHub, so people could find such projects by searching for that tag rather than us having to update a Readme in some community-maintained repo.

[f-f]

I generally agree with @milesfrain that doing a git clone should be enough, but I think the main problem we have at hand is "discoverability", i.e. how would people know that:

1. there are templates available
2. which templates are up for grabs
3. ..and which of them are actually any good

So I think curating a page in the official documentation would be nice - I'd even go as far as having a small list of templates in the purescript.org homepage, to get people started with something useful as quickly as possible

@JordanMartinez to clarify on this, I think there's value in curating a list vs collecting it automatically (e.g. via the mechanism you propose), because of the 3rd point I mentioned, which can be summarized as "quality assurance"

[JordanMartinez]

@f-f I agree. I think my proposed solution is a very fast way to get something going now, but not the best long-term solution.

[milesfrain]

I'd even go as far as having a small list of templates in the purescript.org homepage

Agreed. This is also what TypeScript does.[1]

How do we decide which templates to feature?

Here are some ideas for criteria:

• Template and framework are compatible with latest PS compiler
• Framework documentation published to Pursuit
• Only one template per framework
• (?) Template maintained either under framework org or PS org
• (?) Template utilized in at least one up-to-date tutorial

I think it's also important to be strict with removing or demoting any templates that don't meet the above criteria so new users aren't led astray. Encourage reporting of template and framework problems, and then quickly remove them from the "featured" list if the issues remain unresolved. Experienced users will still be able to find these templates, and will hopefully feel some obligation to get them reinstated.

[1] Side note: Their React link is outdated and incorrect. Documentation is hard, even with staff on payroll!

[hdgarrood]

I might suggest moving this discussion to discourse: https://discourse.purescript.org. It might get a bit more traction there?

[f-f]

I'll close this since it looks like it's something that should be done outside of Spago, and the discussion has moved to Discourse

[f-f]

Reopening this as we have a more pressing usecase now: a better test setup based on spec-node, as implemented in #1264. We should add spec-node to the default init template as it's useful, but we should have a more minimal template that we could use in tests here (since spec-node carries quite many dependencies)

[fsoikin]

Didn't we agree that this shouldn't be in the beta milestone?

[f-f]

@fsoikin it's up for grabs so can be done whenever really 😄