Skip to content

Latest commit

 

History

History
103 lines (77 loc) · 4.43 KB

development.md

File metadata and controls

103 lines (77 loc) · 4.43 KB

Garden development

You're here because you want to get into the codebase. That's great. This guide will help you dig in. If you haven't already, please see the contribution documentation for a project overview along with versioning, development, and PR workflows.

Package creation

One of the best ways to get familiar with Garden's package structure is to create your own. Garden makes this simple by providing a npm run new command. This command will prompt you to enter a name (e.g. test). The new package will be generated under /packages and you can view the results by running the npm start command.

Unless you are a member of the core team, it is unlikely that we'll accept brand new package PRs. However, a new package provides the simplified sandbox for exploring further component development concepts. In the mean time, please open an issue to discuss the addition of a new component package.

Package structure

All packages follow this basic structure (.e.g. under /packages/test):

  • ├── demo/ – visual component demos
  • ├── src/ – component source code and spec tests
          ├── elements/ – high abstraction components that wrap interaction behavior and visual styling
          ├── styled/ – view-level styled-components that contain theme based CSS
          └── index.ts – public-facing component exports for this package
  • ├── package.json – configuration for the package published to the registry
  • ├── README.md – essential package description, install, and usage instructions

The Garden React codebase is statically type-checked using TypeScript. See the API documentation for in-depth treatment of Garden's Container-View-Element architecture, along with rules that apply to each component type. See Garden's TypeScript documentation for standard interface and type rules.

Package demos

Package demo code is generated via Storybook. Run npm start to build and serve package documentation in development mode (with hot reloading). See demo documentation for development information.

Package testing

The Garden react-components repo is strongly tested – holding steady at ~95% coverage. DOM testing is implemented using React Testing Library while Jest is the underlying API (describe - it - expect) and test runner.

All exported elements must be tested, but should be limited to the surface area exposed by the component (in other words, don't re-test imported react-containers). All styled views may also benefit from testing – asserting that various options affect one or two notable CSS values in question.

In cases where DOM structure or state would be unwieldy to determine, data-test-* attributes can be added in complex components to aid with testing. These attributes will be removed from published components during the build process.

Linting and formatting

All JS/TS, CSS, and Markdown files are linted using eslint, stylelint, and markdownlint respectively. Additionally, prettier is used to format all JS/TS, and package.json files.

Package dependencies

Garden attempts to keep package dependencies to a minimum. Typical package dependencies include:

  • Dependencies
    • polished
  • Peer dependencies
    • @zendeskgarden/react-theming
    • react
    • react-dom
    • styled-components

When additional dependencies are required, they can be installed with the lerna add. The Renovate bot will keep these dependencies up-to-date over time.

Package build

Garden packages are built using Rollup. Package distribution files include:

  • CommonJS bundle (the package main entry)
  • ES module bundle (the package module entry)
  • type definitions

Run a full repo build using npm run build or a package-scoped build with npm run build -- --scope @zendeskgarden/react-[package].