If you choose to get started without Docker, ensure that you are building dev-portal
with Node v16. Otherwise, to use Docker,
refer to the following section, Using Docker.
yarn install
yarn dev
open https://localhost:3000
open dev-portal.code-workspace
Ensure Docker is installed on your machine before following these steps. To use Docker with this repository, you can either use Docker's CLI or Docker Compose, both of which are defined in more detail below:
# Build Docker Container
$ docker build -t dwolla/dev-portal:0.1.0 .
# Start Docker Container
$ docker run [-d] -p 3000:3000 \
-v "$(pwd)"/:/app \
-v /app/.mdx-data \
-v /app/.next \
-v /app/node_modules \
dwolla/dev-portal:0.1.0
# Build Docker Container
$ docker-compose build
# Start Docker Container
$ docker-compose up [-d]
# Destroy Docker Container
$ docker-compose down
yarn install
- Install dependenciesyarn dev
- Start development serveryarn test{,:ci,:coverage}
- Run testsyarn checks
- Run Prettier, TypeScript, ESLint checksyarn fix
- Attempt to fix Prettier, TypeScript, ESLint errorsyarn build
- Build for productionyarn build-storybook
- Build Storybookyarn start
- Start production serveryarn storybook
- Start Storybook
The framework powering dev-portal
, Next.js, centers around pages.
In Next.js, a page is a React Component exported from a
.js
,.ts
, or.tsx
file in thepages
directory. Each page is associated with a route based on its file name.Example: If you create
pages/about.js
that exports a React component like below, it will be accessible at/about
.
In addition, dev-portal
supports .mdx
pages which:
- are Markdown files
- define metadata as YAML frontmatter
- can embed React components
For example:
---
category: "" # Which category doc is displayed under in sidebar
title: "" # Doc title when linked to
# Defining a `group` on `index.mdx` groups docs in same folder
group:
category: "" # Overrides individual doc categories
title: "" # Group title that can be expanded in sidebar
---
Page content
<MyComponent />
Categories can be ordered in the side nav by creating a _section.yml
file in a section's root directory (e.g. pages/guides/_section.yml
).
categories:
- "Getting Started"
- "Customers"
- "Funding Sources"
- "Webhooks"
In addition to pages, the following can be found in /components
:
layout
components- render the layout surrounding a page
partial
components- render parts within a page
atom
components- building blocks extracted from
layout
andpartial
components
- building blocks extracted from
util
components- don't contain markup or styles
Components are organized based on their relationship to pages.
As a rule of thumb, start with a layout
or partial
component. Which one depends on where the component is rendered relative to a page:
layout
components are rendered outside the pagepartial
components are rendered within the page
atom
components can be extracted from layout
and partial
components when an abstraction becomes apparent. In general, it's a good idea to wait until you have some concrete use cases for an abstraction before creating one.
- https://terodox.tech/one-two-n-pattern/
- https://overreacted.io/goodbye-clean-code/
- https://www.sandimetz.com/blog/2016/1/20/the-wrong-abstraction
util
components are different than other types of components in that they don't contain markup or styles. util
components are good candidates for breaking out into their own library/package at some point.
Prefix styled components with Styled*
, for example:
const StyledContainer = styled.div`
padding: 10px;
`;
const MyComponent = () => <StyledContainer>MyComponent</StyledContainer>;