mirror of
https://github.com/shoelace-style/webawesome.git
synced 2026-01-12 04:09:12 +00:00
6387dffe75
* 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
114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# Web Awesome
|
||
|
||
- Works with all frameworks 🧩
|
||
- Works with CDNs 🚛
|
||
- Fully customizable with CSS 🎨
|
||
- Includes an official dark theme 🌛
|
||
- Built with accessibility in mind ♿️
|
||
- Open source 😸
|
||
|
||
Built by the folks behind [Font Awesome](https://fontawesome.com/).
|
||
|
||
---
|
||
|
||
Documentation: [webawesome.com](https://webawesome.com)
|
||
|
||
Source: [github.com/shoelace-style/webawesome](https://github.com/shoelace-style/webawesome)
|
||
|
||
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.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.
|
||
|
||
If that's not what you're trying to do, the [documentation website](https://webawesome.com) is where you want to be.
|
||
|
||
### What are you using to build Web Awesome?
|
||
|
||
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.
|
||
|
||
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?
|
||
|
||
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.
|
||
|
||
Individual packages are also free to install `devDependencies` as needed as long as they are specific to that package only.
|
||
|
||
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 <package-name>`).
|
||
|
||
### Forking the Repo
|
||
|
||
Start by [forking the repo](https://github.com/shoelace-style/webawesome/fork) on GitHub, then clone it locally and install dependencies.
|
||
|
||
```bash
|
||
git clone https://github.com/YOUR_GITHUB_USERNAME/webawesome
|
||
cd webawesome
|
||
npm install
|
||
```
|
||
|
||
### Developing
|
||
|
||
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 browsers don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically.
|
||
|
||
### Building
|
||
|
||
To generate a production build, run the following command.
|
||
|
||
```bash
|
||
cd packages/webawesome
|
||
npm run build
|
||
```
|
||
|
||
You can also run `npm run build:serve` to start an [`http-server`](https://www.npmjs.com/package/http-server) instance on `http://localhost:4000` after the build completes, so you can preview the production build.
|
||
|
||
### Creating New Components
|
||
|
||
To scaffold a new component, run the following command, replacing `wa-tag-name` with the desired tag name.
|
||
|
||
```bash
|
||
cd packages/webawesome
|
||
npm run create wa-tag-name
|
||
```
|
||
|
||
This will generate a source file, a stylesheet, and a docs page for you. When you start the dev server, you'll find the new component in the "Components" section of the sidebar.
|
||
|
||
### Adding additional packages
|
||
|
||
Right now the only additional packages are in private repositories.
|
||
|
||
To add additional packages from other repositories, run `git clone <url> packages/<package-name>` to clone your repo into `packages/`.
|
||
|
||
Make sure to run `npm install` at the root of the monorepo after adding your package!
|
||
|
||
### Contributing
|
||
|
||
Web Awesome is an open source project and contributions are encouraged! If you're interesting in contributing, please review the [contribution guidelines](CONTRIBUTING.md) first.
|
||
|
||
## License
|
||
|
||
Web Awesome is available under the terms of the [MIT License](LICENSE.md).
|