Update developement docs

packages/lit-dev-content/site/guide/tools/development.md

@@ -6,89 +6,163 @@ eleventyNavigation:
   order: 2
 ---
 
-{% todo %}
+During the development phase of your projects when you're writing Lit components, the following tools can help boost your productivity:
 
-- Rough content from lit-html docs follows. Update & edit this content for Lit.
-- ES dev server => web-dev-server
-- Add content on Using TypeScript?
-
-{% endtodo %}
+* A dev server, for previewing code without a build step.
+* TypeScript, for writing type-checked code.
+* A linter, for catching Javascript errors.
+* A code formatter, for consistently formatting code.
+* Lit-specific IDE plugins, for linting and syntax-highlighting Lit templates.
 
+Check out the [Getting Started](../../getting-started) documentation to easily setup a development environment with all of these features pre-configured.
 
-During the development phase, you might want the following tools:
+## Using a dev server { #devserver }
 
-* IDE plugins, for linting and code highlighting.
-* Linter plugins, for checking lit-html templates.
-* A dev server, for previewing code without a build step.
+Lit is packaged as JavaScript modules, and it uses bare module specifiers that are not yet natively supported in most browsers. Bare specifiers are commonly used, and you may want to use them in your own code as well. For example:
 
+```js
+import {LitElement, html, css} from 'lit';
+```
 
-## IDE plugins
+To run this code in the browser, the bare specifier ('lit') needs to be transformed to a URL that the browser can load (such as '/node_modules/lit/lit.js').
 
-There are a number of IDE plugins that may be useful when developing with lit-html. In particular, we recommend using a code highlighter that works with lit-html style templates. In addition, we recommend using a linter like ESLint that supports modern JavaScript.
+There are many development servers that can deal with module specifiers. If you already have a dev server that does this and integrates with your build process, that should be sufficient.
 
-The following VS Code and TypeScript plugins check lit-html templates for errors:
+If you need a dev server, we recommend [Web Dev Server](https://modern-web.dev/docs/dev-server/overview/).
 
-* [VS Code plugin](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin)
+### Web Dev Server
 
-* [TypeScript plugin (works with Sublime and Atom)](https://github.com/runem/lit-analyzer/tree/master/packages/ts-lit-plugin)
+[Web Dev Server](https://modern-web.dev/docs/dev-server/overview/) is an open-source dev server that enables a build-free development process.
 
-More plugins
+It handles rewriting bare module specifiers to valid URLs, as required by browsers.
 
-The [awesome-lit-html](https://github.com/web-padawan/awesome-lit-html#ide-plugins) repo lists other IDE plugins.
+Install Web Dev Server:
 
+```bash
+npm i @web/dev-server --save-dev
+```
 
-## Linting
+Add a command to your `package.json` file:
 
-ESLint is recommended for linting lit-html code.  The following ESLint plugin can be added to check for some common issues in lit-html templates:
+```json
+"scripts": {
+  "start": "web-dev-server --node-resolve --app-index index.html --open --watch --esbuild-target auto"
+}
+```
 
-* [https://github.com/43081j/eslint-plugin-lit](https://github.com/43081j/eslint-plugin-lit)
+Run the dev server:
 
-Another alternative is to use the `lit-analyzer` CLI alongside ESLint to detect issues in your lit-html templates:
+```bash
+npm run start
+```
 
-* [https://github.com/runem/lit-analyzer/tree/master/packages/lit-analyzer](https://github.com/runem/lit-analyzer/tree/master/packages/lit-analyzer)
+For older browsers like IE11, Web Dev Server can transform JavaScript modules to use the backwards-compatible SystemJS module loader, and automatically serve the web components polyfills. You'll need to configure the `@web/dev-server-legacy` package to support older browsers.
 
-`lit-analyzer` uses the same backend as the VS Code and TypeScript plugins listed in [IDE plugins](#ide-plugins).
+Install the Web Dev Server legacy package:
 
-## Dev server
+```bash
+npm i @web/dev-server-legacy --save-dev
+```
 
-lit-html is packaged as JavaScript modules. Many developers prefer to import modules using bare module specifiers:
+Configure `web-dev-server.config.js`:
 
 ```js
-import {html, render} from 'lit-html';
+import { legacyPlugin } from '@web/dev-server-legacy';
+
+export default {
+  plugins: [
+    // make sure this plugin is always last
+    legacyPlugin({
+      polyfills: {
+        webcomponents: true,
+        // Inject lit's polyfill-support module into test files, which is required
+        // for interfacing with the webcomponents polyfills
+        custom: [
+          {
+            name: 'lit-polyfill-support',
+            path: 'node_modules/lit/polyfill-support.js',
+            test: "!('attachShadow' in Element.prototype)",
+            module: false,
+          },
+        ],
+      },
+    }),
+  ],
+};
 ```
 
-To run in the browser, the bare identifier ('lit-html') needs to be transformed to a path or URL that the browser can load (such as '/node_modules/lit-html/lit-html.js'). [ES dev server](https://open-wc.org/developing/es-dev-server.html) is an open-source dev server that handles this and other transforms.
+For full installation and usage instructions, see the [Web Dev Server documentation](https://modern-web.dev/docs/dev-server/overview/).
 
-You can also use the Polymer CLI dev server, if you already have it installed. For new projects, we recommend the ES dev server.
+## Using TypeScript { #typescript }
 
-If you already have a dev server that integrates with your build process, you can use that, instead.
+TypeScript extends the Javascript language by adding support for types. Types are useful for catching errors early and making code more readable and understandable.
 
-### ES Dev Server
+To install TypeScript in your project:
 
-The ES dev server enables a build-free development process. It handles rewriting bare module specifiers to valid paths or URLs, as required by the browser. For IE11, ES dev server also transforms JavaScript modules to use the backwards-compatible SystemJS module loader.
+```bash
+npm install typescript --save-dev
+```
 
-Install ES dev server:
+To build the code:
 
 ```bash
-npm i -D es-dev-server
+npx tsc --watch
 ```
 
-Add a command to your `package.json` file:
+For full installation and usage instructions, see the [TypeScript site](https://www.typescriptlang.org/). To get started, the sections on [installing TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-tooling-in-5-minutes.html) and [using its features](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) are particularly helpful.
 
-```json
-"scripts": {
-  "start": "es-dev-server --app-index index.html --node-resolve --watch --open"
-}
+## Setting up Javascript linting { #linting }
+
+Linting can help catch errors in your code. We recommend using [ESLint](https://eslint.org) for linting Lit code.
+
+To install ESLint in your project:
+
+```bash
+npm install eslint --save-dev
+npx eslint --init
 ```
 
-Run the dev server:
+To invoke it:
 
 ```bash
-npm run start
+npx eslint yourfile.js
 ```
 
-For full installation and usage instructions, see the [open-wc website](https://open-wc.org/developing/es-dev-server.html).
+For full installation and usage instructions, see the [ESLint documentation](https://eslint.org/docs/user-guide/getting-started).
+
+Integrating linting into your IDE workflow can help catch errors as early as possible. See [Lit-specific IDE plugins](#ide-plugins) to configure linting specifically for Lit.
+
+## Setting up formatting { #formatting }
+
+Using a code formatter can help ensure code is consistent and readable. Integrating your formatter of choice with your IDE ensures your code is always clean and tidy.
+
+A few popular options include:
+
+* [Prettier](https://prettier.io/): [VS Code plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+* [Beautifier](https://beautifier.io/): [VS Code plugin](https://marketplace.visualstudio.com/items?itemName=HookyQR.beautify)
+* [Clang](https://www.npmjs.com/package/clang-format): [VS Code plugin](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)
+
+
+## Using Lit-specific IDE plugins { #ide-plugins }
+
+There are a number of IDE plugins that may be useful when developing with Lit. In particular, we recommend using a syntax highlighter that works with Lit templates.
+
+The following plugins highlight Lit templates and check them for errors:
+
+* [`lit-plugin` for VS Code](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin)
+
+* [`ts-lit-plugin` for TypeScript](https://github.com/runem/lit-analyzer/tree/master/packages/ts-lit-plugin) (works with Sublime and Atom)
+
+* [`eslint-plugin-lit` for ESLint](https://github.com/43081j/eslint-plugin-lit)
+
+These plugins provide:
 
-## Using TypeScript
+- Syntax highlighting
+- Type-checking
+- Code completion
+- Hover-over docs
+- Jump to definition
+- Linting
+- Quick Fixes
 
-TODO
+See the [awesome-lit-html](https://github.com/web-padawan/awesome-lit-html#ide-plugins) repo for other IDE plugins, as well as additional tools and information.