|
| 1 | +<!-- Generated breadcrumbs - DO NOT EDIT --> |
| 2 | + |
| 3 | +[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Working in the SWC repo |
| 4 | + |
| 5 | +<!-- Document title (editable) --> |
| 6 | + |
| 7 | +# Working in the SWC repo |
| 8 | + |
| 9 | +<!-- Generated TOC - DO NOT EDIT --> |
| 10 | + |
| 11 | +<details open> |
| 12 | +<summary><strong>In this doc</strong></summary> |
| 13 | + |
| 14 | +- [About this guide](#about-this-guide) |
| 15 | +- [Getting started](#getting-started) |
| 16 | + - [Prerequisites](#prerequisites) |
| 17 | + - [Installation](#installation) |
| 18 | +- [Repository structure](#repository-structure) |
| 19 | +- [Development workflow](#development-workflow) |
| 20 | + - [Developing](#developing) |
| 21 | + - [Testing](#testing) |
| 22 | + - [Linting](#linting) |
| 23 | + - [Building](#building) |
| 24 | +- [Command reference](#command-reference) |
| 25 | + |
| 26 | +</details> |
| 27 | + |
| 28 | +<!-- Document content (editable) --> |
| 29 | + |
| 30 | +## About this guide |
| 31 | + |
| 32 | +This guide covers the essential information you need to work effectively in the Spectrum Web Components (SWC) repository. |
| 33 | + |
| 34 | +## Getting started |
| 35 | + |
| 36 | +### Prerequisites |
| 37 | + |
| 38 | +Before you begin, ensure you have the following installed: |
| 39 | + |
| 40 | +- **Node.js**: Version 20.10.0 or higher (check with `node --version`) |
| 41 | +- **Yarn**: Version 4.6.0 or higher (check with `yarn --version`) |
| 42 | +- **Git**: For version control (check with `git --version`) |
| 43 | + |
| 44 | +### Installation |
| 45 | + |
| 46 | +1. Clone the repository: |
| 47 | + |
| 48 | +```bash |
| 49 | +git clone https://github.com/adobe/spectrum-web-components.git |
| 50 | +``` |
| 51 | + |
| 52 | +2. Install dependencies: |
| 53 | + |
| 54 | +```bash |
| 55 | +cd spectrum-web-components |
| 56 | +yarn install |
| 57 | +``` |
| 58 | + |
| 59 | +## Repository structure |
| 60 | + |
| 61 | +SWC is currently in transition from its first generation (**1st-gen**) to its second generation (**2nd-gen**). |
| 62 | + |
| 63 | +> This transition is motivated by some important strategic goals. For more information, see [Objectives and Strategy](../../03_project-planning/01_objectives-and-strategy.md). |
| 64 | +
|
| 65 | +Instead of creating a separate branch or repo for 2nd-gen, we are working on the 1st-gen and 2nd-gen projects side-by-side in this repository, with some core functionality being shared between 1st- and 2nd-gen components. This strategy makes it easier for us to continue actively improving and supporting 1st-gen even as we devote much of our attention to defining and building 2nd-gen. |
| 66 | + |
| 67 | +Reflecting the side-by-side strategy, the repository is organized into two top-level workspaces: |
| 68 | + |
| 69 | +- **`1st-gen/`** contains all of the 1st-gen packages, tooling, and supporting materials. |
| 70 | + |
| 71 | + Most of what lives here will be left behind in the transition to 2nd-gen; the core component functionality we'll carry forward is gradually being moved into the `2nd-gen` workspace. |
| 72 | + |
| 73 | + While we'll continue doing work in `1st-gen` as needed to accomplish our goals, we expect this work to decrease steadily toward none. |
| 74 | + |
| 75 | +- **`2nd-gen/`** is a new workspace that we're building from the ground up to serve as a clean foundation for our future work. It includes: |
| 76 | + - A Core library (`packages/core/`), which contains the functionality shared between 1st- and 2nd-gen |
| 77 | + |
| 78 | + - The 2nd-gen SWC library (`packages/swc/`). |
| 79 | + |
| 80 | +During this transition, depending on what you're trying to accomplish, you may end up working in `1st-gen`, `2nd-gen`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help. |
| 81 | + |
| 82 | +## Development workflow |
| 83 | + |
| 84 | +The project's top-level `package.json` file defines [several commands](#command-reference) that can be run from the repository root, covering the most important parts of the development workflow. |
| 85 | + |
| 86 | +> By default, each command is run in both the 1st-gen and 2nd-gen workspaces, but you can add a `:1st-gen` or `:2nd-gen` suffix to any command to run it for only one workspace. |
| 87 | +
|
| 88 | +### Developing |
| 89 | + |
| 90 | +We use Storybook to interact with and test components as we develop them, as well as to document components and demonstrate usage patterns for our customers. There are separate Storybooks for 1st- and 2nd-gen. |
| 91 | + |
| 92 | +**To start Storybook:** |
| 93 | + |
| 94 | +```bash |
| 95 | +yarn start |
| 96 | +``` |
| 97 | + |
| 98 | +This command launches Storybook for both 1st- and 2nd-gen and opens a browser tab for each. |
| 99 | + |
| 100 | +### Testing |
| 101 | + |
| 102 | +**To run all tests:** |
| 103 | + |
| 104 | +```bash |
| 105 | +yarn test |
| 106 | +``` |
| 107 | + |
| 108 | +### Linting |
| 109 | + |
| 110 | +The linter runs before each commit, but you can also run it manually. |
| 111 | + |
| 112 | +**To check for linting issues:** |
| 113 | + |
| 114 | +```bash |
| 115 | +yarn lint |
| 116 | +``` |
| 117 | + |
| 118 | +### Building |
| 119 | + |
| 120 | +You should rarely need to trigger build explicitly, but you can do so as necessary. |
| 121 | + |
| 122 | +**To build all packages:** |
| 123 | + |
| 124 | +```bash |
| 125 | +yarn build |
| 126 | +``` |
| 127 | + |
| 128 | +## Command reference |
| 129 | + |
| 130 | +Here are the most frequently used commands available from the repository root: |
| 131 | + |
| 132 | +| Command | Description | |
| 133 | +| -------------------- | -------------------------------------------- | |
| 134 | +| `yarn start` | Start Storybook for both 1st-gen and 2nd-gen | |
| 135 | +| `yarn start:1st-gen` | Start Storybook for 1st-gen only | |
| 136 | +| `yarn start:2nd-gen` | Start Storybook for 2nd-gen only | |
| 137 | +| `yarn test` | Run tests for both 1st-gen and 2nd-gen | |
| 138 | +| `yarn test:1st-gen` | Run tests for 1st-gen only | |
| 139 | +| `yarn test:2nd-gen` | Run tests for 2nd-gen only | |
| 140 | +| `yarn lint` | Check for linting issues (staged files) | |
| 141 | +| `yarn lint:1st-gen` | Check for linting issues in 1st-gen only | |
| 142 | +| `yarn lint:2nd-gen` | Check for linting issues in 2nd-gen only | |
| 143 | +| `yarn build` | Build all packages (2nd-gen then 1st-gen) | |
| 144 | +| `yarn build:1st-gen` | Build 1st-gen packages only | |
| 145 | +| `yarn build:2nd-gen` | Build 2nd-gen packages only | |
| 146 | + |
| 147 | +For more specific workflows and advanced topics, refer to the other contributor guides. |
0 commit comments