Should we ship a CLI out-of-the-box?

[matanlurey]

Some stakeholders:

• Devs: @leonsenft @alorenzen
• Build system for Dart: @jakemac53 @natebosch
• PM: @kevmoo
• Ecosystem and Docs: @chalin @nshahan

This would fix or obsolete @filiph's #380.

Background

In upcoming releases, we will potentially end support for pub serve/build for a new faster and incremental development cycle using package:build_runner (and friends). There are a lot of moving pieces, but ultimately build_runner, under that name or another CLI, will support out-of-the-box DDC and Dart2JS with builders replacing transformers.

We have an option of encapsulating some of that logic in an AngularDart CLI, i.e.:

$ pub run angular <doctor|serve|build|test|deploy|create|...>

The idea here is that we wouldn't re-invent anything, but instead delegate:

• serve, build ➡️ pkg/build_runner
• test ➡️ pkg/build_runner + pkg/test
• ...

In this scenario, I imagine the following:

$ pub run angular

> AngularDart CLI is not installed. Add it by including in your pubspec.yaml:
>
> dev_dependencies:
>   angular_cli: ^1.0.0

(Once added)

$ pub run angular serve

> Building with build_runner v1.0.0 ...
> ...
> Serving at localhost:8080/

Options

No CLI

We'd do nothing here (status quo) and rely on external infrastructure and perhaps provide docs.

CLI without build or test system integration

Basically, explain how to use build_runner and test, but no specific integration.

We might include a CLI, but it would be Angular-specific, for example angular doctor to help diagnose issues, or angular create to create scaffolds, but we'd just provide documentation on using external infrastructure for build/serve/test.

CLI with tight build and test system integration

Basically, automatically setup build_runner and test and maintain it for our users.

In this case, we'd basically wrap build/serve/test infrastructure, providing a one-stop shop for common AngularDart actions, but without requiring users to know about the underlying infrastructure (and if we are blocked, we can always provide AngularDart-specific workarounds).

Risks

Not providing a CLI or omitting integration

• An MVP of Dart4Web doesn't have the necessary polish to be easily used.
• AngularDart users that are used to the pub serve/build ease today are turned off.
• Minor blocking issues aren't easily resolvable or need manual workarounds in client code.

Providing a CLI with integration

• MVP of Dart4Web gets less (direct) use and feedback due to us wrapping them.
• We provide idioms or functionality that isn't reproducible on other Dart4Web packages.
• We diverge from the "golden path" when introducing minor fixes or workarounds.

---

Thoughts?

[alorenzen]

I definitely think we should have a CLI, but am a little unsure if it should be provided by Angular or by the Dart4Web effort.

[nshahan]

• @devoncarew

We have started discussing work for a CLI for next quarter.

[natebosch]

one downside of shipping a CLI that passes through to build_runner is that it becomes a dependency rather than a dev_dependency which makes rolling breaking changes harder. As it stands build is the main point of version coupling which is (hopefully) more stable than build_runner is.

The benefit is that users already have the dep on angular so pub run angular just works, whereas if we don't do this they'll need to manually add a dev_dependency on build_runner.

[jakemac53]

An MVP of Dart4Web doesn't have the necessary polish to be easily used.
AngularDart users that are used to the pub serve/build ease today are turned off.

Would pub run build_runner serve/build/watch/test resolve these?

We provide idioms or functionality that isn't reproducible on other Dart4Web packages.

This would be my primary concern - but as long as it is just a wrapper I don't think it would be an issue. Any additional functionality deemed generally useful could be upstreamed and then wrapped.

MVP of Dart4Web gets less (direct) use and feedback due to us wrapping them.

I don't think this would be much of an issue, we could watch the angular repo for issues or the angular team could forward them to us, either should be ok.

[matanlurey]

@alorenzen:

I definitely think we should have a CLI, but am a little unsure if it should be provided by Angular or by the Dart4Web effort.

This question isn't really mutually exclusive, it's more of should Angular provide one.

---

@nshahan:

@devoncarew We have started discussing work for a CLI for next quarter.

Anything you can share (privately or publicly)? I want to make sure this meets our needs.

---

@natebosch:

one downside of shipping a CLI that passes through to build_runner is that it becomes a dependency rather than a dev_dependency which makes rolling breaking changes harder.

Well, it depends. We could for example have angular_cli shrinkwrap a version of build_runner (via a snapshot), or require users to also have a dev_dependency on build_runner (and have the tooling help them).

As it stands build is the main point of version coupling which is (hopefully) more stable than build_runner is.

Yup, it's probably close to being able to be 1.0 I assume?

The benefit is that users already have the dep on angular so pub run angular just works, whereas if we don't do this they'll need to manually add a dev_dependency on build_runner.

That's my thought exactly.

---

@jakemac53:

An MVP of Dart4Web doesn't have the necessary polish to be easily used.
AngularDart users that are used to the pub serve/build ease today are turned off.

Would pub run build_runner serve/build/watch/test resolve these?

Sure, but then we're beholden to (a) those features being completed and (b) those features being implemented the ways best to serve AngularDart customers. They probably will be, but having our own entry-point means we can tweak as needed without requiring breaking changes to build_runner.

We provide idioms or functionality that isn't reproducible on other Dart4Web packages.

This would be my primary concern - but as long as it is just a wrapper I don't think it would be an issue. Any additional functionality deemed generally useful could be upstreamed and then wrapped.

That's my thought too, but wanted to have it as a risk anyway.

MVP of Dart4Web gets less (direct) use and feedback due to us wrapping them.

I don't think this would be much of an issue, we could watch the angular repo for issues or the angular team could forward them to us, either should be ok.

Yup. SG.

[natebosch]

Yup, it's probably close to being able to be 1.0 I assume?

Yeah we hope to have build at 1.0 soon. build_runner will not likely go 1.0 for a while since we expect to need breaking changes based on feedback.

[jakemac53]

Sure, but then we're beholden to (a) those features being completed and (b) those features being implemented the ways best to serve AngularDart customers. They probably will be, but having our own entry-point means we can tweak as needed without requiring breaking changes to build_runner.

It does also give you the option of changing build systems etc if desired/necessary, without affecting your users as much.

At the same time it makes angular different than the rest of the ecosystem, but as long as it still works with the standard tools as well then it doesn't really matter. Essentially, it could just be an opt-in layer on top of the default stuff that provides some additional commands etc.

[jakemac53]

Another option here could be making the unified cli tool have a plugin architecture so you could just install the angular plugin. That could get complicated, but I don't think it has to be if you keep the functionality limited (for instance only allow new commands, make new commands just delegate to other binaries, etc).

[matanlurey]

Another option here could be making the unified cli tool have a plugin architecture so you could just install the angular plugin

Might be good for a M+n release, but I wouldn't want this for an MVP.

My idea for the Angular CLI is basically to do be MVP + Angular addons/checks. If the entire MVP goes smooth enough, we might end up making angular just directly delegate to build_runner most of the time anyway. On the other hand if there are complications/edge-cases, we have the ability to massage the interaction a bit.

[matanlurey]

Superseded by dart-lang/webdev#1 after discussion.

[devoncarew]

@matanlurey, re:

Anything you can share (privately or publicly)? I want to make sure this meets our needs.

I'll send you the repo - there's a POC pretty far along. It uses pub build and pub serve, but that's a placeholder for now. The code that's there may or may not be what migrates to dart-lang/webdev, but the general intent is what we want (a unified web development experience, building on the existing dart cli tools, and using package:build and friends).