From 73094993021694bc0facda358dbabdf77468f435 Mon Sep 17 00:00:00 2001 From: Frederic Salmen <4583669+salmenf@users.noreply.github.com> Date: Wed, 13 Nov 2024 11:25:02 +0100 Subject: [PATCH] Update quickstart and debug for WebWriter web --- .../website/src/content/docs/debugging.md | 6 +++--- .../website/src/content/docs/quickstart.md | 18 +++++++++++------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/@webwriter/website/src/content/docs/debugging.md b/@webwriter/website/src/content/docs/debugging.md index 3db88a9f..2271c679 100644 --- a/@webwriter/website/src/content/docs/debugging.md +++ b/@webwriter/website/src/content/docs/debugging.md @@ -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. diff --git a/@webwriter/website/src/content/docs/quickstart.md b/@webwriter/website/src/content/docs/quickstart.md index 0bf39bf0..53d674a7 100644 --- a/@webwriter/website/src/content/docs/quickstart.md +++ b/@webwriter/website/src/content/docs/quickstart.md @@ -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. \ No newline at end of file