New iFixit e-commerce site.
git clone https://github.com/iFixit/react-commerce.git
cd react-commerce
nvm use
:nvm use && algoliaApiKey=123xyz ./startReactCommerce.sh
Not your first time? If you have previously setup the algolia api key (i.e. it is still saved in
frontend/.env.local
), you don't need to specify it again.Note: You may use an alternative method of getting the correct node version instead of nvm.
Copy the Search API Key
from Algolia (You may need to ask for access to our Algolia)
Copy the dev key from Cominor:
cat /etc/dozuki/algolia-keys.json | jq --raw-output .searchApiKey
Here's one way you can get all the right versions installed and setup:
nvm use
node
and npm
npm install -g pnpm@8
npm install -g yarn
We use Verdaccio as our private npm registry. To install packages from Verdaccio, you will need to setup an authentication token.
You can retrieve the token from Slack and then save it to .env.local
as VERDACCIO_AUTH_TOKEN
.
Otherwise, you can follow the steps below to create a new token:
backend/.env.example
to backend/.env
pnpm setup && source ~/.bashrc
(if you haven't already done so)pnpm install -g vercel
vercel login
cd path/to/this/repo && vercel link --project=react-commerce
iFixit
scope when it asks which scope to usevercel env pull
ln -s ../.env frontend/.env.local
frontend/.env.local.example
to frontend/.env.local
frontend/.env.local
fill in ALGOLIA_API_KEY
by either:
Search API Key
from Algolia
cat /etc/dozuki/algolia-keys.json | jq --raw-output .searchApiKey
SENTRY_AUTH_TOKEN
is not needed in developmentThis command will install both backend and frontend dependencies:
pnpm install:all
This command will start Strapi dev server and Next.js dev server:
pnpm dev
After running the dev server, you can access the site at http://localhost:3000/Parts
or http://localhost:3000/Tools
:warning:
http://localhost:3000/
is not yet routed and will 404.
After running the dev server, you can access the Strapi admin panel at http://localhost:1337/admin
. To login use email strapi@ifixit.com
and password Password1
.
The local Strapi dev server will allow you to make changes to the schema of content types. When you're satisfied with the changes, you can push into a new branch to get a preview url from govinor.
Next.js's dev server automatically listens to localhost:3000
as well as your local IP address and the same port. This means that you can access the dev server from other devices on your network. This is useful for testing on mobile devices.
EX: http://192.168.1.123:3000
However, if you are using a firewall, you may need to allow incoming connections to port 3000.
The running firewall is mostlikely ufw
.
To allow incoming connections to port 3000, run:
sudo ufw allow 3000
To remove the rule, run:
sudo ufw delete allow 3000
The project contains a backend
folder with Strapi config and a frontend
with Next.js.
You can run the backend both using SQLite and using Postgres with docker compose. For now the recommended approach for local dev is to just use SQLite.
:warning: If you are running Strapi using docker compose, be sure to delete
backend/node_modules
first, as your OS might differ from the docker container OS, so you want the docker container to install dependencies by itself.
The frontend
directory is structured as follows:
pages
: contains the Next.js routes (usually these just export code from a template)models
: contains business logic (e.g. how to fetch product list from API, how to subscribe to newsletter, etc.)templates
: you can think of these as view controllers. Templates are especially useful to handle multiple routes (e.g. product list template is used by several routes, like /Parts
, /Tools
, /Parts/Mac
etc.).layouts
: contains the layouts that each page can use. Right now we only have a default layout, but in the future we might have pages that will require to use a different layout component.components
: contains the React view componentshelpers
: contains reusable custom app-related helper functionslib
: contains custom libraries that can stand on their own (e.g. lib/strapi-sdk
). Think of these as packages that potentially could be used in other projects.assets
: contains assets imported from view components (e.g. svg illustrations)public
: contains the static filesconfig
: contains app configurable settings (e.g. environment variables, constants, etc.)Here's an overview of the production setup (the focus is on Next.js, therefore details on the iFixit app have been left out):
We use Jest and Playwright (with MSW) to run our tests.
At the moment, we only have tests for the frontend
. These tests are located in the frontend/tests
directory.
⚠️ We don't need to have the dev server running before we run the Jest tests.
You can use the following command to run all the Jest
tests:
pnpm test
Additionally, you can pass any Jest
flag to the command by prepending --
before the flags:
pnpm test -- --watch
pnpm test -- ProductListItem --updateSnapshot
⚠️ Note: You will not be able to interact with the Jest CLI prompt if the tests were ran from the root
directory. To be able to interact with the Jest CLI prompt, you will need to run the tests from the frontend
directory.
Root Dir Execution | Frontend Execution |
---|---|
For more information on Jest flags, click on the link to read the docs: Jest CLI
⚠️ We need the dev server running to run the Playwright tests. You can run the dev server by running
pnpm dev
in theroot
directory.You can also just let Playwright start the dev server automatically when running the tests, but this will make running Playwright tests slower as it will need to start the dev server every time.
You can use the following command to run all Playwright
tests:
pnpm playwright:run
If you want to debug all the tests, or a single test, you can use the following command:
pnpm playwright:debug [test_name]
timeout
to 0
(no timeout)playwright
object in the browser to allow you to interact with Playwright's Locator API right from the browser's consoleAdditionally, you can directly add any Playwright
flag to the command:
pnpm playwright:run --project="Desktop Chrome" fix_kit
pnpm playwright:run --project="Mobile Chrome" --headed fix_kit
For more information on Playwright flags, click on the link to read the docs: Playwright CLI
⚠️ For more Playwright specific information such as Mocking API Requests and debugging tips, check out the testing-doc
To create feature flags the project uses an approach based on environment variables.
react-commerce
: One is essentially a staging project (react-commerce
), and the other is for production (react-commerce-prod
).Setup a flag key: In the frontend/config/flags.ts
file, add a new flag key to the flags dictionary. For example:
export const flags = {
// ...
STORE_HOME_PAGE_ENABLED:
process.env.NEXT_PUBLIC_FLAG__STORE_HOME_PAGE_ENABLED === 'true',
};
Local Development: Set the flag to true
in your frontend/.env.development
file. This lets you access the feature during local development. For example:
NEXT_PUBLIC_FLAG__STORE_HOME_PAGE_ENABLED=true
Note: If you need to override the flag in your local development environment, you can set the flag to
false
in yourfrontend/.env.local
file.
Staging: Go to Vercel react-commerce
project settings, and add the environment variable for the flag, setting it to true
. You don't need to select any branch or environment — just leave all the checkboxes checked.
Production: Finally, when you're ready to roll out the feature, set the environment variable to true
in the Vercel react-commerce-prod
project settings.
Note: It's not necessary to set the flag to
false
while developing the feature. If the flag is not set, it will default tofalse
.
To use the flag, you can just import the flags dictionary from frontend/config/flags.ts
and use it in your code. For example:
import { flags } from '@config/flags';
function Page() {
// ...
if (!flags.STORE_HOME_PAGE_ENABLED) return notFound();
// ...
}
react-commerce
previews, without needing to know about the feature flags.react-commerce
preview can be use to QA the changes with feature flags enabled, and the react-commerce-prod
preview can be used to QA the changes with feature flags disabled.If you want to use an svg as a React component, add it to frontend/assets/svg/files
and run
pnpm run transform-svg
The script will take svg files and transform them into React components that you can import like this:
import { LifetimeWarrantyIcon } from '@assets/svg';
:warning: SVGR uses the name of the file to name the component (it converts it to camel case), so name the svg accordingly.
When you need to update the Shopify Storefront SDK version, follow these steps:
NEXT_PUBLIC_SHOPIFY_STOREFRONT_VERSION
in frontend/.env
pnpm dev
)The public Shopify storefront API is rate limited by user IP. To avoid hitting the rate limit when making requests from the server, we use Shopify storefront API with a delegate access token. To generate a token for a shop, use the automation bot:
pnpm bot shopify create delegate-token
:information_source: You can use the Admin API Password of the app that you use to generate the Storefront access token.
Since OSX 12.3, python(2) is no longer available by default.
If no prebuilt image is available for some dependencies like sqlite3, it may be necessary to install python(2) to build the image locally.
Brew has discontinued the python@2 formula, so one way to install it is via pyenv
:
brew install pyenv
pyenv install 2.7.18
pyenv global 2.7.18
echo 'PATH=$(pyenv root)/shims:$PATH' >> ~/.zshrc
With the latest changes, we might run into a situation where the local strapi does not have the ifixit test store in it. In order to fix this add the folowing to backend/.env
STRAPI_ADMIN_ENABLE_ADDONS_DANGEROUS_ACTIONS=true
With the latest version of main, go to your local strapi at http://localhost:1337/admin/plugins/addons and hit Reset Seed
with the domain set to main.govinor.com
.
If this page does not appear, then delete backend/.cache
and backend/dist
and re-start the dev server.
Whenever you update the Shopify Storefront schema version, you need to run pnpm codegen:download-shopify-storefront-schema
to download the new schema.