From 6387dffe75a89608c334b4295e8ccc05cbba1107 Mon Sep 17 00:00:00 2001 From: randomguy-2650 <150704902+randomguy-2650@users.noreply.github.com> Date: Mon, 29 Sep 2025 18:32:58 +0200 Subject: [PATCH] Make the README better (#1494) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Make the README better • Replace straight quotes with smart quotes • Revise Node.js minimum requirement wording (to prevent line breaks) • Replace old links to LitElement (Polymer) to Lit • Replace mentions of “NPM” with “npm”, as per https://github.com/npm/cli?tab=readme-ov-file#is-it-npm-or-npm-or-npm • Fix some grammar and abbreviations • Made “dependencies” and “devDependencies” mentions unquoted to be consistent • Correct “MIT license” with “MIT License”, as per https://opensource.org/license/mit * Make some specific changes to make wording more clear * add missing dot * remove smart quotes --- README.md | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 5ee564a42..5a4b827d0 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Twitter: [@webawesomer](https://twitter.com/webawesomer) ## Developers ✨ -Developers can use this documentation to learn how to build Web Awesome from source. You will need Node >= 14.17 to build and run the project locally. +Developers can use this documentation to learn how to build Web Awesome from source. You will need Node.js 14.17 or later to build and run the project locally. **You don't need to do any of this to use Web Awesome!** This page is for people who want to contribute to the project, tinker with the source, or create a custom build of Web Awesome. @@ -29,31 +29,29 @@ If that's not what you're trying to do, the [documentation website](https://weba ### What are you using to build Web Awesome? -Components are built with [LitElement](https://lit-element.polymer-project.org/), a custom elements base class that provides an intuitive API and reactive data binding. The build is a custom script with bundling powered by [esbuild](https://esbuild.github.io/). +Components are built with [Lit](https://lit.dev/), a custom elements base class that provides an intuitive API and reactive data binding. The build is a custom script with bundling powered by [esbuild](https://esbuild.github.io/). ### Understanding the Web Awesome monorepo -Web Awesome uses [NPM workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces) for its monorepo structure and is fairly minimal in what it provides. +Web Awesome uses [npm workspaces](https://docs.npmjs.com/cli/v11/using-npm/workspaces) for its monorepo structure and is fairly minimal in what it provides. -By using a NPM workspaces and a monorepo structure, we can get consistent builds, shared configurations, and reduced duplication across repositories which reduces regressions and forces consistency across `webawesome`, `webawesome-pro`, and `webawesome-app`. +By using npm workspaces and a monorepo structure, we can get consistent builds, shared configurations, and reduced duplication across repositories which reduces regressions and forces consistency across `webawesome`, `webawesome-pro`, and `webawesome-app`. Generally, if you plan to only work with the free version of `webawesome` it is easiest to go to `packages/webawesome` and run all commands from there. -### Where do NPM dependencies go? +### Where do npm dependencies go? -Any dependencies intended to be used across all packages (IE: `prettier`, `eslint`) that are _NOT_ used at runtime should be in the root `devDependencies` of `package.json`. +Any dependencies intended to be used across all packages (i.e., `prettier`, `eslint`) that are **not** used at runtime should be in the root `devDependencies` of `package.json`. ```bash npm install -D -w prettier ``` -Any dependencies that will be used at runtime by a package should be part of the specific package's `"dependencies"` such as `lit`. This is required because if that dependency is not in the `packages/*/package.json`, it will not be installed when used via NPM. +Any dependencies that will be used at runtime by a package should be part of the specific package's `dependencies` such as `lit`. This is required because if that dependency is not in the `packages/*/package.json`, it will not be installed when used via npm. -Individual packages are also free to install devDependencies as needed as long as they are specific to that package only. +Individual packages are also free to install `devDependencies` as needed as long as they are specific to that package only. -To do install a package specific to a package, change your working directory to that package's root - -IE: `cd packages/webawesome && npm install ` +To install a package specific to a Web Awesome package, change your working directory to that package's root (i.e., `cd packages/webawesome && npm install `). ### Forking the Repo @@ -67,14 +65,14 @@ npm install ### Developing -Once you've cloned the repo, run the following command from the respective directory within `packages/*` +Once you’ve cloned the repo, run the following command from the respective directory within `packages/*`. ```bash cd packages/webawesome npm start ``` -This will spin up the dev server. After the initial build, a browser will open automatically. There is currently no hot module reloading (HMR), as browser's don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically. +This will spin up the dev server. After the initial build, a browser will open automatically. There is currently no hot module reloading (HMR), as browsers don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically. ### Building @@ -102,7 +100,7 @@ This will generate a source file, a stylesheet, and a docs page for you. When yo Right now the only additional packages are in private repositories. -To add additional packages from other repositories, run: `git clone packages/` to clone your repo into `packages/`. +To add additional packages from other repositories, run `git clone packages/` to clone your repo into `packages/`. Make sure to run `npm install` at the root of the monorepo after adding your package! @@ -112,4 +110,4 @@ Web Awesome is an open source project and contributions are encouraged! If you'r ## License -Web Awesome is available under the terms of the MIT license. \ No newline at end of file +Web Awesome is available under the terms of the [MIT License](LICENSE.md).