Clean up extension template and docs

[bajtos]

This is a follow-up for #5337 and #5122

The documentation for component authors (e.g. Creating components) and the template used by lb4 extension are outdated. We learned a lot since those artifacts were written and introduced new conventions and features, e.g. @config decorator. It's time to modernize both the CLI template and the docs to the latest and greatest.

Acceptance criteria

CLI templates

Update the template used by lb4 extension to follow the current style as seen e.g. in extensions/metrics

• inject the target app and component config to the component class
• add a new file src/keys.ts exporting {ComponentName}Keys.COMPONENT binding key
• decorate the component class with @bind(),
• include generic Basic Use instructions in the scaffolded README file

Nice to have:

• use the component name in the file names to disambiguate them from similar files in other extensions, e.g. src/{name}.keys.ts and src/{name}.component.ts

Docs

Revisit the documentation, make it consistent with the current style for writing extensions and the CLI template.

• Creating components
  • Rework "Configuring components" at the end to explain how to receive and provide component config via @config and
    this.configure() API
  • Review the content - are the advices and code snippets still current and consistent with recommendations we are giving elsewhere? Are we missing any major information? (It's probably best to open follow-up stories to make non-trivial docs updates.)
• Extending LoopBack 4,
  • "Learn from existing ones" - can we add more of our existing components to the list?
  • Review the content - are the advices and code snippets still current and consistent with recommendations we are giving elsewhere? Are we missing any major information? (It's probably best to open follow-up stories to make non-trivial docs updates.)
• Using components
  • Update the list of components to include all extensions developed in loopback-next monorepo (look for components both in extensions and packages)
• Components

Nice to have:

• Review the content in the pages above and in the component migration guide (https://loopback.io/doc/en/lb4/migration-extensions.html and sub-pages). Some content may be duplicated (sometimes inconsistently), some content may belong to a different place. Decide what to do (if anything) and either make the changes right away or create follow-up issues.

[hacksparrow]

@bajtos lb4 extension is creating the extension dir in the project root. Is it by design? Can we change it? Shouldn't extensions be kept in a extensions dir?

[hacksparrow]

Also, why call it "Extension" when we are creating a Component? Can we name the command lb4 component instead? Breaking change, but it leaves no room for confusion.

[raymondfeng]

lb4 extension is creating the extension dir in the project root. Is it by design? Can we change it? Shouldn't extensions be kept in a extensions dir?

lb4 extension should just create a new project as an extension package for LoopBack 4. It should not be used inside an existing LB app. For loopback-next, use https://github.com/strongloop/loopback-next/blob/master/bin/create-package.js.

[raymondfeng]

Also, why call it "Extension" when we are creating a Component? Can we name the command lb4 component instead? Breaking change, but it leaves no room for confusion.

I would like to reserve lb4 component to add a component to an existing application.

[bajtos]

@bajtos lb4 extension is creating the extension dir in the project root. Is it by design? Can we change it? Shouldn't extensions be kept in a extensions dir?

I have no idea, TBH. I believe this behavior was introduced by @raymondfeng, please check with him. Also, have you checked the discussion in the pull request introducing lb4 extension command? The answer may lay there.

Also, why call it "Extension" when we are creating a Component? Can we name the command lb4 component instead? Breaking change, but it leaves no room for confusion.

In my view, the term "component" includes both built-in components (e.g. context & TS decorator metadata) and add-on components/extensions (e.g. @loopback/metrics).

On the other hand, "extension" is for things that are outside of the "core" framework. In loopback-next, we have a top-level directory extensions too.

If you want to unify our vocabulary and use a single term (which I think is a great idea!), then IMO we should use "extension", not "component".

IIRC, we started to use the term "component" early in LB4 development. Later we pivoted to use "extension", but we did not propagate that change to existing docs.

[hacksparrow]

Created this follow up task - #6232.

[hacksparrow]

Closed via #6158.