This is the @lit-internal/playground
package. Inspired by (and
loosely compatible with) the
Lit.dev playground, it provides
an easy way to spin up small example projects that depend on the
monorepo's packages, for the purpose of testing, exploration,
demonstration, etc.
The monorepo playground is intended to support any use case that benefits from having a live example running in a dev server while working on monorepo packages. For example:
- Reproducing and fixing bugs
- Manual testing of behaviors that are difficult to test via automated tests alone
- Rapid iteration on alternatives when exploring new features
For some use cases, examples may be throw-aways, used during
local development and never committed; the playground includes
a scratch
folder for this purpose. For other use cases, it may
be useful to commit examples to the repo, either temporarily or
permanently.
- Make it easy and fast to spin up an example
- Provide an instant-feedback workflow, similar to the Lit.dev playground
- Support Gist-based import / export from the Lit.dev playground that that "just works" for common cases
- Establish a simple, flexible filesystem layout that allows examples to be committed to the repo when useful, while cleanly separating the playground implementation (scripts, templates, etc.) from individual examples
- Editing / updating existing Lit.dev plaground examples
- 100% robust Lit.dev playground import and export
Run the scripts below from the playground
directory.
Note:
- Examples live in subfolders beneath
playground/p
- When specifying the path to an example, you may include the
leading
p/
for auto-complete, or omit for brevity - If you don't intend to commit an example, you can put it
beneath the
scratch
folder (playground/p/scratch
) to make Git ignore it
npm run new -- my-example
- Creates a new example (in this case, at
playground/p/my-example'
) by cloning a minimal template - Alternatively, you can create an example from scratch,
anywhere under
playground/p
npm run start -- my-demos/cool-demo
- Launches a dev server (with the root, in this case, at
playground/p/my-demos/cool-demo
)
npm run import -- timer ee310ee9432d7a634852c8b9a56f95a9
- Creates a new example (in this case, at
playground/p/timer
) by importing from a Gist - Second argument may be any string containing a 32-character, alphanumeric Gist ID (e.g., a Lit.dev playground URL)
- The import script constructs a
package.json
, derived from the Gist's originalpackage.json
(if any) and source files
npm run export -- my-example
- Creates a new Gist from the specified example
- Requires manual installation of this gist CLI
- Changes to example source files will result in automatic, immediate HMR-based updates
- Changes to a Lit monorepo package generally require manual rebuilding of the package, with an update being triggered automatically upon completion of the build
- While the observance of certain conventions is useful for Lit.dev playground compatibility, there are essentially no special requirements or restrictions on how you build examples
- The dev server is launched with the example directory as its root
- If you don't need to export to a Gist, you can use subfolders to organize files
- The
index.html
file (if present) will be served if you browse to the server's localhost port without specifying a path - If your example requires more structure, you can access other HTML files by path and/or use client-side routing
- JavaScript and TypeScript files can be used interchangeably, with
TypeScript files being transpiled on the fly; when referring to
script files, always use the
.js
extension, regardless of whether the source file is JavaScript or TypeScript - Other subresources (CSS, images, fonts, etc.) may be loaded as
usual, relative to the server root
/
or the referring file./
- Usage of Vite-specific features (loaders, etc.) is discouraged
- If an example depends only on Lit monorepo packages, there is
no need to include a
package.json
(though the template example does include an emptypackage.json
for convenience) - If an example depends on external packages or requires a specific
released version of a Lit monorepo package, just add a
package.json
file and use thenpm
CLI directly in the example folder to manage and install dependencies
-
Since Gists don't support nested folders, you should use a flat structure for any example you might want to export
-
The Lit.dev playground expects a single HTML entrypoint, at
index.html
-
The Lit.dev playground supports implicit (undeclared) dependencies, but the monorepo playground does not (with the exception of Lit monorepo packages)
-
The provided
import
script constructs apackage.json
, derived from the Gist's originalpackage.json
(if any) and source files- If the original
package.json
explicitly depends on any Lit monorepo packages, these dependencies are omitted from the constructedpackage.json
so that they will be loaded from the current monorepo source instead - If the Gist's JavaScript or TypeScript source files import any
modules from external packages that are not included in the
Gist's
package.json
, these packages are added to the constructedpackage.json
(though only top-level, static imports are detected)
- If the original
-
Upon successful completion, the
import
script writes a file named_import.info.json
to the example folder, containing the source Gist ID and the contents of the Gist's originalpackage.json
file -
The
export
script requires manual installation of this gist CLI -
The
import
andexport
scripts do minimal error detection; they're designed to "just work" for common cases but don't enforce compliance with structural requirements and may be tripped up by edge cases -
The
@lit-internal/playground
package is a workspace within the monorepo so that its dependencies (TypeScript and Vite) are installed vianpm install
at the monorepo root -
Individual examples are not workspaces; each example's external dependencies (if any) are installed locally
-
Examples use the Vite dev server
- Vite's
resolveId
hook makes it easier to support seamless import and export of examples from the Lit.dev playground (specifically, allowing.ts
source files to be loaded from HTML files using.js
file extensions—something that the Lit.dev playground requires but which isn't supported out of the box by either Vite or@web/dev-server
). - Vite's transparent runtime TypeScript transpilation also
appears to be more robust than
@web/dev-server
's - Individual examples need not specify a dependency on Vite,
provided that the dev server is launched from the
playground
directory using the provided NPM script
- Vite's