Conversation
KVSRoyal
added
documentation
|
/docs |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #801 +/- ##
=======================================
Coverage 85.81% 85.81%
=======================================
Files 505 505
Lines 22823 22823
Branches 2657 2657
=======================================
Hits 19586 19586
Misses 2909 2909
Partials 328 328 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
|
||
| Here in the config, we: | ||
| - Register the type and asset definitions with the `LSPAssetsPlugin`, so the validator and compiler can leverage them. It is common to register the shared types and assets in a CLI Preset, since it reduces redundant CLI configuration across projects. | ||
| - Add a custom `ExampleValidationPlugin` to the config. `ExampleValidationPlugin`, in this scenario, is a `PlayerLanguageServicePlugin` your team has written. (See [Adding Custom LSP Validations](../custom-lsp-validations) for an example of how and why one might want to write a custom plugin.) It is common to add custom validation plugins to the CLI Preset, since it reduces redundant CLI configuration across projects. |
There was a problem hiding this comment.
Oh yeah, it's broken because the page doesn't exist yet. It gets added in this PR: #787.
|
|
||
| </Steps> | ||
|
|
||
| ### With Bazel |
There was a problem hiding this comment.
Unsure, but, is Bazel the preferred option? If yes, we should list it first
There was a problem hiding this comment.
I guess Bazel is probably preferred since we're trying to move everyone over to a Bazel monorepo. Moving
KVSRoyal
force-pushed
the
cli-preset-docs
branch
from
6a08447 to
5307bce
Compare
|
/docs |
KVSRoyal
force-pushed
the
cli-preset-docs
branch
from
5307bce to
bdff0eb
Compare
|
/docs |
KVSRoyal
force-pushed
the
cli-preset-docs
branch
from
bdff0eb to
3cc78c5
Compare
|
|
||
| You are a developer on a team that has a large number of projects that use Player. You want to create a CLI Preset that will be used across all of these projects. This preset will include the necessary plugins and type definitions to provide a consistent development experience. | ||
|
|
||
| This specific example leverages `Node.js` and `TypeScript`, but those are not requirements for creating a CLI preset. The important thing is that the preset is a reusable configuration (in this case, it is exported as a package) that can be applied to multiple projects. |
There was a problem hiding this comment.
This specific example leverages
Node.jsandTypeScript, but those are not requirements for creating a CLI preset
I'm not sure what this means. The Player CLI is a JavaScript application so Node.JS is effectively required. I don't believe we've tested it with any other JavaScript engine. Technically TypeScript is not required as you could write these examples in JavaScript but I'm not sure what the usecase would be there. These specifics seem not worth calling out as they are really tangential to what we're actually discussing here.
There was a problem hiding this comment.
That info helps a lot actually--I'm not super familiar with the web side of things and wasn't sure if this was similar to other stuff where there are infinite ways to do it 😅 . Updating!
|
|
||
| Consider this **hypothetical** scenario: | ||
|
|
||
| You are a developer on a team that has a large number of projects that use Player. You want to create a CLI Preset that will be used across all of these projects. This preset will include the necessary plugins and type definitions to provide a consistent development experience. |
There was a problem hiding this comment.
You are a developer on a team that has a large number of projects that use Player.
To avoid confusion with teams who author plugins and integrate Player, I would call out the benefit that CLI plugins drive is meant to be realized in content authoring use cases.
| This example includes the following dependencies: | ||
|
|
||
| - `@player-tools/cli` <Badge text="required"/>: The Player CLI package. It is required to define any CLI preset. | ||
| - `@player-ui/types` <Badge text="required"/>: The Player UI types package. This provides type definitions (e.g. `Asset`, `Flow`, etc.) that serve as the foundation for the Player ecosystem. We will add it to the config in this example. Every project will want these type definitions for compilation and validation, so it's an excellent addition to the reusable config. |
There was a problem hiding this comment.
Every project will want these type definitions for compilation and validation, so it's an excellent addition to the reusable config.
It should be called out that this version should match the version of Player being used at runtime to make sure that the Player types being used for authorship are the same as the types used when actually running content.
| - `@player-ui/types` <Badge text="required"/>: The Player UI types package. This provides type definitions (e.g. `Asset`, `Flow`, etc.) that serve as the foundation for the Player ecosystem. We will add it to the config in this example. Every project will want these type definitions for compilation and validation, so it's an excellent addition to the reusable config. | ||
|
|
||
| Strictly speaking, you can exclude this package and provide your own type definitions package. However, this is not recommended, as you would have to ensure your custom types were compatible with other Player plugins and tools. | ||
| - `@my-org/player-plugin-assets` <Badge text="example-only" variant="caution"/>: A custom plugin package that, in this scenario, your team has written. We will add it to the config in this example to provide basic asset types. In this scenario, every project is using these asset types, so it's an excellent addition to the reusable config for compilation & validation. |
There was a problem hiding this comment.
A custom plugin package that, in this scenario, your team has written. We will add it to the config in this example to provide basic asset types.
It might be worth it to link to the XLR doc on exporting types from plugins to fully connect the dots in terms of what including the plugin here is actually doing.
KVSRoyal
force-pushed
the
cli-preset-docs
branch
from
3cc78c5 to
dc1bbd6
Compare
|
/docs |
KVSRoyal
force-pushed
the
cli-preset-docs
branch
from
dc1bbd6 to
d582a37
Compare
KVSRoyal
force-pushed
the
cli-preset-docs
branch
from
d582a37 to
7aae37b
Compare
4 participants
Addresses #464.
Add a simple guide / tutorial for how to create and use a CLI Preset.
Change Type (required)
Indicate the type of change your pull request is:
patchminormajorN/ADoes your PR have any documentation updates?