mirror of
https://github.com/empayre/fleet.git
synced 2024-11-06 17:05:18 +00:00
140 lines
6.0 KiB
Markdown
140 lines
6.0 KiB
Markdown
# Fleet frontend
|
|
|
|
The Fleet frontend is a Single Page Application using React with Typescript and Hooks.
|
|
|
|
## Table of contents
|
|
- [Running the Fleet web app](#running-the-fleet-web-app)
|
|
- [Testing](#testing)
|
|
- [Directory Structure](#directory-structure)
|
|
- [Patterns](#patterns)
|
|
- [Storybook](#storybook)
|
|
|
|
## Running the Fleet web app
|
|
|
|
For details instruction on building and serving the Fleet web application
|
|
consult the [Contributing documentation](../docs/Contributing/README.md).
|
|
|
|
## Testing
|
|
|
|
Visit the [overview of Fleet UI testing](../docs/Contributing/Fleet-UI-Testing.md) for more information on our testing strategy, philosophies, and tools.
|
|
|
|
To run unit or integration tests in `ComponentName.tests.tsx`, run `yarn test -- ComponentName.tests.tsx`. To [test all Javascript components](https://fleetdm.com/docs/contributing/testing-and-local-development#javascript-unit-tests) run `yarn test`.
|
|
|
|
|
|
[QA Wolf](https://www.qawolf.com/) manages our E2E test and will maintain the tests as well as raise
|
|
any issues found from these tests. Engineers should not have to worry about working with E2E testing
|
|
code or raising issues themselves.
|
|
|
|
For more information on how our front-end tests work, visit our [frontend test
|
|
directory](./test/README.md).
|
|
|
|
## Directory structure
|
|
|
|
Component directories in the Fleet front-end application encapsulate the entire
|
|
component, including files for the component and its styles. The
|
|
typical directory structure for a component is as follows:
|
|
|
|
```
|
|
└── ComponentName
|
|
├── _styles.scss
|
|
├── ComponentName.tsx
|
|
|-- ComponentName.tests.tsx
|
|
├── index.ts
|
|
```
|
|
|
|
- `_styles.scss`: The component css styles
|
|
- `ComponentName.tsx`: The React component
|
|
- `ComponentName.tests.tsx`: The React component unit/integration tests
|
|
- `index.ts`: Exports the React component
|
|
- This file is helpful as it allows other components to import the component
|
|
by it's directory name. Without this file the component name would have to
|
|
be duplicated during imports (`components/ComponentName` vs. `components/ComponentName/ComponentName`).
|
|
|
|
### [components](./components)
|
|
|
|
The component directory contains global React components rendered by pages, receiving props from
|
|
their parent components to render data and handle user interactions.
|
|
|
|
### [context](./context)
|
|
|
|
The context directory contains the React Context API pattern for various entities.
|
|
Only entities that are needed across the app has a global context. For example,
|
|
the [logged in user](./context/app.tsx) (`currentUser`) has multiple pages and components
|
|
where its information is pulled.
|
|
|
|
### [interfaces](./interfaces)
|
|
|
|
Files in the interfaces directory are used to specify the Typescript interface for a reusable Fleet
|
|
entity. This is designed to DRY up the code and increase re-usability. These
|
|
interfaces are imported in to component files and implemented when defining the
|
|
component's props.
|
|
|
|
**Additionally, local interfaces are used for props of local components.**
|
|
|
|
### [layouts](https://github.com/fleetdm/fleet/tree/main/frontend/layouts)
|
|
|
|
The Fleet application has only 1 layout, the [Core Layout](./layouts/CoreLayout/CoreLayout.jsx).
|
|
The Layout is rendered from the [router](./router/index.tsx) and are used to set up the general
|
|
app UI (header, sidebar) and render child components.
|
|
The child components rendered by the layout are typically page components.
|
|
|
|
### [pages](./pages)
|
|
|
|
Page components are React components typically rendered from the [router](./router).
|
|
React Router passed props to these pages in case they are needed. Examples include
|
|
the `router`, `location`, and `params` objects.
|
|
|
|
### [router](./router)
|
|
|
|
The router directory is where the react router lives. The router decides which
|
|
component will render at a given URL. Components rendered from the router are
|
|
typically located in the [pages directory](./pages). The router directory also holds a `paths`
|
|
file which holds the application paths as string constants for reference
|
|
throughout the app. These paths are typically referenced from the [App
|
|
Constants](./app_constants) object.
|
|
|
|
### [services](./services)
|
|
|
|
CRUD functions for all Fleet entities (e.g. `query`) that link directly to the Fleet API.
|
|
|
|
### [styles](./styles)
|
|
|
|
The styles directory contains the general app style setup and variables. It
|
|
includes variables for the app color hex codes, fonts (families, weights and sizes), and padding.
|
|
|
|
### [templates](./templates)
|
|
|
|
The templates directory contains the HTML file that renders the React application via including the `bundle.js`
|
|
and `bundle.css` files. The HTML page also includes the HTML element in which the React application is mounted.
|
|
|
|
### [test](./test)
|
|
|
|
The test directory includes test helpers, API request mocks, and stubbed data entities for use in test files.
|
|
More on test helpers, stubs, and request mocks [here](./test/README.md).
|
|
|
|
### [utilities](./utilities)
|
|
|
|
The utilities directory contains re-usable functions and constants for use throughout the
|
|
application. The functions include helpers to convert an array of objects to
|
|
CSV, debounce functions to prevent multiple form submissions, format API errors,
|
|
etc.
|
|
|
|
## Patterns
|
|
|
|
The list of patterns used in the Fleet UI codebase can be found [here](./docs/patterns.md).
|
|
|
|
## Storybook
|
|
|
|
[Storybook](https://storybook.js.org/) is a tool to document and visualize components, and we
|
|
use it to capture our global components used across Fleet. Storybook is key when developing new
|
|
features and testing components before release. It runs a separate server exposed on port `6006`.
|
|
To run this server, do the following:
|
|
|
|
- Go to your root fleet project directory
|
|
- Run `make deps`
|
|
- Run `yarn storybook`
|
|
|
|
The URL `localhost:6006` should automatically show in your browser. If not, visit it manually.
|
|
|
|
Running Storybook before implementing new UI elements can clarify if new components need to be created or already exist. When creating a component, you can create a new file, `component.stories.tsx`, within its directory. Then, fill it with the appropriate Storybook code to create a new Storybook entry. You will be able to visualize the component within Storybook to determine if it looks and behaves as expected.
|