Skip to content

Commit

Permalink
Update quickstart and debug for WebWriter web
Browse files Browse the repository at this point in the history
  • Loading branch information
salmenf committed Nov 13, 2024
1 parent a046a38 commit 7309499
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 10 deletions.
6 changes: 3 additions & 3 deletions @webwriter/website/src/content/docs/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ WebWriter includes several features to support testing and debugging.
While it is possible to develop widgets in any setup, the recommended way is to use the "local packages" feature. Using the "create/import" button in package management mode (three boxes button), you can create or import a package in a local folder. This way, you can test and debug your packages directly in WebWriter without needing to publish new package releases constantly.

### Auto-reloading
For each package, you can enable auto-reloading. When auto-reloading is enabled, your package's folder is observed and WebWriter reloads the package on each change. This functionality is similar to a development server, a common tool in web development.
Your package's build is automatically observed and WebWriter reloads the package on each change. This functionality is similar to a development server, a common tool in web development.

### Error reporting
When a package is loaded, is it bundled (e.g. dependencies are included, TypeScript is transpiled, and so on). WebWriter records all occuring errors. When a package produces errors, it is marked in red and its' members can't added to explorables anymore. Instead, you can click the package name to view all issues. Issues are also output to the console.
When a package is loaded, it is bundled (e.g. dependencies are included, TypeScript is transpiled, and so on). WebWriter records all occuring errors. When a package produces errors, it is marked in red and its' members can't added to explorables anymore. Instead, you can click the package name to view all issues. Issues are also output to the console.

## Developer tools
For debugging, the most helpful approach is to make use of the built-in developer tools. They are available in WebWriter and match your system webview (e.g. Edge Devtools for Windows, Safari Devtools for Mac). You can find [more information here](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/What_are_browser_developer_tools).
For debugging, the most helpful approach is to make use of the built-in developer tools. They are available in your browser. You can find [more information here](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/What_are_browser_developer_tools).

## `DEV` statements
Using a lesser known feature of JS/TS ([labeled statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label)), WebWriter allows you to mark certain statements in your widget code as development statements. These statements are only executed in WebWriter when the package is loaded locally. They are *not* executed when an author installs the published package or when the explorable is saved.
Expand Down
18 changes: 11 additions & 7 deletions @webwriter/website/src/content/docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,26 @@ This guide takes you through a few, quick steps of setup. When done, you will ha
To get started, you need...
- [ ] ...a text editor of your choice, for example [VSCode](https://code.visualstudio.com/)
- [ ] *optional*: The [`lit-plugin`](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin) extension for VSCode if you plan to use Lit - it adds support for syntax highlighting, type checking and code completion for Lit.
- [ ] ...[WebWriter](https://webwriter.app/get_started)
- [ ] ...[WebWriter running in **Chrome** or **Edge**](https://run.webwriter.app/)

## Quick Start in WebWriter
Get started by developing your widget inside WebWriter.

### Step 1: Create a local package
Open WebWriter. Toggle the package managing mode (three boxes icon on the left). Then click the "Create/import" button. Choose a directory where your package will be located. The dialog will help you pick a valid package/widget name. Once you are done, confirm to create the package. *You may need to restart WebWriter after this step!*
Open WebWriter. Toggle the package managing mode (three boxes icon on the left). Then click the "Create/import" button. Choose a directory where your package will be located. The dialog will help you pick a valid package/widget name. Once you are done, confirm to create the package. In some cases, you need to reload the packages afterwards by clicking the three boxes icon again.

### Step 2: Edit your widget
In your chosen package directory, you can find your widget's files. If you chose the default "Lit" template, there will be a file `my-widget.ts` (named after your package) containing a basic scaffold for your widget. Try changing the code. Once you save your changes, WebWriter should automatically reload your widget so you see your changes immediately. Otherwise, toggling package managing mode (as described above) or manually restarting WebWriter should also achieve this.
### Step 2: Set up automatic rebuilding
WebWriter automatically detects changes in the build of your package, triggering a reload. If you use the "Lit" template, you can run `npm run dev` in your project root, meaning the package will be rebuilt automatically if your source code changes.

### Step 3: Edit your widget
In your chosen package directory, you can find your widget's files. If you chose the default "Lit" template, there will be a file `widgets/my-widget.ts` (named after your package) containing a basic scaffold for your widget. Try changing the code. Once you save your changes, WebWriter should automatically reload your widget so you see your changes immediately. Otherwise, toggling package managing mode (as described above) should also achieve this.

### What does the default "Lit" template include?
It uses the `LitElementWw` base class from the `@webwriter/lit` package, supporting these features in your widget:
1. Core properties as attributes: `contentEditable` is already set up as a reactive property.
2. Scoped Custom Element Registry: [ScopedElementsMixin](https://open-wc.org/docs/development/scoped-elements/) is used to avoid name collisions between two widgets using the same third-party web components.
3. Rehydration: Custom elements based on LitElementWw will be set to the state of their attributes when loaded.
1. Core properties as attributes: `contentEditable` and `lang` are already set up as reactive properties.
2. Localization support: The widget can support localization for any number of languages. Follow the [localization guide](./widgets/localization) to implement that.
3. Scoped Custom Element Registry: [ScopedElementsMixin](https://open-wc.org/docs/development/scoped-elements/) is used to avoid name collisions between two widgets using the same third-party web components.
4. Rehydration: Custom elements based on LitElementWw will be set to the state of their attributes when loaded.

### What next?
Now that your setup is ready, you read more about [widgets](./widgets/widgets) and follow the documentation (see navigation) to implement features.

0 comments on commit 7309499

Please sign in to comment.