TRANCE STACK

Warning This stack is typescript and NPM only for now.

The NPM requirement comes from the GitHub actions scripts. I will make it possible to use both pnpm and yarn soon, but it requires a bit more time and I would love to get feedback on the stack until then.

What's included

This is a Remix stack that offers a way to ship production ready remix applications. It is constructed in an opinionated way and is meant to be used as a starting point for your own remix projects. You can modify it to your liking and use it as a base for your own remix projects.

📦 Click to see a list of included technologies

Good security practices with CSP and sensible auth processes
i18n with i18next and its remix integration remix-i18next
Auth0 for authentication
Split for feature flags
Sentry for Client Side error tracking (server side soon)
CookieYes for cookie consent
Analytics Integrations
Static Types with TypeScript
Linting with ESLint
Unit testing with Vitest and Testing Library
End-to-End testing with Playwright
Conventional Commits for commit messages to enable automated versioning
semantic-release for automatic release management
Storybook v7 for component development
NPM for package management (for now. Will have support for yarn and pnpm soon)
GitHub Actions for a full CI setup
AWS deployment with CDK via GitHub Actions
- Using AWS Lambda + Api Gateway + Cloud Front for production builds
- Using AWS Lambda + Api Gateway for ephemeral builds (for feature branches, pull requests, etc)
Automatic dependency updates with Renovate

Using the stack

Create your project with the stack

npx create-remix@latest --template meza/trance-stack my-app

The setup process will ask you for a GitHub repository name. If you don't have one, don't worry, you can create it after the setup process.

Warning

Read this documentation in your own project's directory from this point onwards. It will contain links relevant to you as the init script will replace the links in this README with the ones customized to your project.

Once it's done, go into the newly created directory and add your git remote

cd my-app && \
git init && \
git add . && \
git commit -m "chore: first commit" && \
git branch -M main && \
git remote add origin https://github.com/meza/trance-stack.git

Make sure that lefthook is set up. Unfortunately, it can only be set up once you have an active git repository.

npx lefthook install

More about lefthook here

Now start the dev server

npm run dev

This has set you up with a default remix application. It won't function well until you complete the setup process. You can find the instructions for that here

Quickstart

Install the dependencies

npm install

Start the dev server

npm run dev

Go through the Getting Started section to set up the local and deployment environments

Notable npm scripts

npm run ci - run the same verification scripts that are run on CI
npm run clean - removes all generated files
npm run clean:all - removes all generated files and all the node_modules directories
npm run dev - Starts the dev server
npm run deploy:dev - Deploys the application to an ephemeral environment
npm run deploy:prod - Deploys the application to production (you probably should never use this one locally)
npm run int - Runs the Playwright integration tests
npm run report - Runs all the things that generate reports for you (coverage, cpd, loc, etc)
npm run storybook - Starts the storybook server
npm run validate - Runs both the CI tests and the integration tests

Getting Started

In order to get this project to work, you will need to have a few things set up first.

The stack is designed in a way that makes it relatively simple to remove the parts you don't need. You will be able to find removal instructions at every step so don't worry if you're not a fan of a particular service.

But... why?

Note We've been using Architecture Decision Records throughout the development of the project so if you ever find yourself wondering why we've chosen a particular service or implementation, you can check the ADR page for more information.

We highly encourage you to keep on adding your own decisions. It's a great way to document the historical context of your project, and it's a great way to share your knowledge with the rest of the team.

We use adr-tools to manage our ADRs. It is installed as part of the dependencies, so you should be able to use it right away.

Environment

Check the project root directory for a .env file. If it's not there, copy the .env.example file to .env

cp .env.example .env

This file contains all the variables you will need to set for the project to function as is.

The APP_DOMAIN should generally stay the same. It's the domain that your application will be served from. This variable will also be set by the deployment scripts, so you don't need to worry about it. During local development it will be set to http://localhost:3000.

The NODE_ENV variable is used to determine which environment you're running the application in. It seems like ARC has a hard time figuring it out on its own, so we've set it up to be set manually. If all goes well, it won't be needed for long.

The SESSION_SECRET variable is used to encrypt the session cookies. It should be a long, random string.

GitHub Settings

Note The project uses GitHub Actions. If you're not familiar with GitHub Actions, you can read more about it here.

You need to do a few things to make sure GitHub Actions can work with your project.

Workflow permissions

First, head over to https://github.com/meza/trance-stack/settings/actions and under the Workflow permissions section, make sure it's on the Read and write permissions option.

Without this, the deployment scripts won't be able to create the necessary GitHub releases.

Branch Protection

Next, head over to https://github.com/meza/trance-stack/settings/branches and add a few branch protection rules.

main
alpha
beta

These are the branches that will be used for the different stages of the application. You can set the settings of these branches however you like, but there's one setting that you need to make sure is unchecked: Allow deletions.

We use this later in the Deployment section to prevent named environments from being deleted.

Pages

Next, head over to https://github.com/meza/trance-stack/settings/pages and make sure the Source is set to GitHub Actions. This will allow us to deploy the project's storybook to GitHub Pages.

Environments

Note We use GitHub environments to manage the different stages of our application. You can read more about them here.

GitHub environments are great to control the environment variables that are used in your workflows.

For now, go to https://github.com/meza/trance-stack/settings/environments and create the following environments:

Production
Staging
Ephemeral

These are referred to in the deployment workflow for example with the environment key. The Ephemeral environment is used for feature branches and pull requests and is referenced in the ephemeral workflow.

Variables vs. Secrets

Some configuration values are sensitive while others are not. For example, the COOKIEYES_TOKEN is not sensitive, but the AUTH0_CLIENT_SECRET is. This mainly comes from the fact that some of these values will be embedded into the html of your application and be visible to everyone.

Warning Please double-check the documentation of the services to ensure you're setting them up correctly.

The application won't work properly if you add a secret as a variable or a variable as a secret.

GitHub Token - Do This First!

For the releases to work properly, you will need to create a Personal Access Token. It needs the following settings:

Expiration: never
Scopes
- repo for private repositories
- public_repo for public repositories

Once you've created the token, go to the secrets settings and add it as GH_TOKEN

Setup for continuous deployment

The deployment processes are described in the Deployment section but to get you started, please create the environment variables and secrets defined in the environment variables section.

Authentication with Auth0

We use Auth0 for authentication. You will need to create an account with them and set up an application.

When creating your new application, make sure to set the following settings:

The application type should be Regular Web Applications
Ignore the Quick Start section
Go to Settings and copy the Domain and Client ID and Client Secret and paste them in the .env file
Set the Token Endpoint Authentication Method to Post
Go to the Allowed Callback URLs section and add http://localhost:3000/auth/callback
Go to the Allowed Logout URLs section and add http://localhost:3000
Go to the Allowed Web Origins section and add http://localhost:3000
Go to the Allowed Origins (CORS) section and add http://localhost:3000
Go to the Refresh Token Rotation section and enable it and with that, you also have to enable the Absolute Expiration option.

Adding the Auth0 variables to GitHub

Now that you have your Auth0 variables, you will need to add them to the GitHub environments you created above.

Go to the secrets settings and add the Auth0 secrets with the same name as the variables in the .env file.

You can set custom values for every environment if you want to. For example, you can set the AUTH0_DOMAIN to dev-123456.eu.auth0.com for the Staging environment and prod-123456.eu.auth0.com for the Production environment.

But for the sake of simplicity, you can just set the same values only once in the main Actions secrets page, and it will be used for all environments.

Enabling the Auth0 integration for feature branch/PR deployments

If you want to enable the Auth0 integration for feature branch/PR deployments, you will need to do a few extra steps. Since the feature branch/PR deployments are ephemeral, they will have a different domain name every time they are deployed. This means that you will need to add the domain name to the Allowed Callback URLs and Allowed Logout URLs

To make this painless, we can use the * wildcard in the domain name. This will allow any domain name to be used.

During the initial setup above, you have added http://localhost:3000 in a few places. You will need to add ,https://*.execute-api.us-east-1.amazonaws.com to the same places. (Note the comma at the beginning. Domains need to be separated by commas)

Note You will need to replace the us-east-1 part with the region you're using.

For example, the Allowed Callback URLs section should look like this:

http://localhost:3000/auth/callback,https://*.execute-api.us-east-1.amazonaws.com/auth/callback

Warning

The * wildcard will allow you to use as wide of a domain name as you would like to. This however comes at the cost of security. We would highly recommend creating an alternative tenant on Auth0 for your feature branch/PR deployments.

Removing the Auth0 integration from the application

Delete the AUTH0_DOMAIN, AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET variables from the .env file and GitHub secrets.
Delete the src/auth.server.ts and the src/auth.server.test.ts files.
Delete the auth0-remix-server dependency from the package.json file.
Follow the compilation and test errors to remove all the code that uses the auth0-remix-server dependency.

CookieYes integration

We use CookieYes for cookie consent. You will need to create an account with them and set up a cookie banner.

When you are prompted with installation instructions or navigate to https://app.cookieyes.com/site-settings, you will need to copy the code following the client_data/ in the script src and paste it in the .env file:

You will also have to go to the variables settings and add the same variable name as the one in the .env file.

Warning The COOKIEYES_TOKEN is set as a variable for the actions.

Removing the CookieYes integration from the application

Delete the COOKIEYES_TOKEN variable from the .env file and GitHub variables.
Delete the src/components/Cookieyes directory.
Delete the relevant types off the appConfig type in the src/types/global.d.ts file.
Delete the <Cookieyes ... /> component and its import from the src/root.tsx file.
Run vitest --run --update to update the snapshots.

Google Analytics 4 integration

We use Google Analytics v4 for analytics. You will need to create an account with them and set up a property.

When you are done setting up your property, you will need to copy the Measurement ID of your Data Stream and paste set the GOOGLE_ANALYTICS_ID variable in the .env file.

You will also have to go to the variables settings and add the same variable name as the one in the .env file.

Warning The GOOGLE_ANALYTICS_ID is set as a variable for the actions.

Removing the Google Analytics 4 integration from the application

Delete the GOOGLE_ANALYTICS_ID variable from the .env file and GitHub variables.
Delete the src/components/GoogleAnalytics directory.
Delete the relevant types off the appConfig type in the src/types/global.d.ts file.
Delete the <GoogleAnalytics ... /> component and its import from the src/root.tsx file.
Run vitest --run --update to update the snapshots.

Hotjar integration

We use Hotjar for heatmaps and user recordings. You will need to create an account with them and set up a new site.

When you have your site set up, head to https://insights.hotjar.com/site/list and copy the ID of your site and paste set the HOTJAR_ID variable in the .env file.

You will also have to go to the variables settings and add the same variable name as the one in the .env file.

Warning The HOTJAR_ID is set as a variable for the actions.

Removing the Hotjar integration from the application

Delete the HOTJAR_ID variable from the .env file and GitHub variables.
Delete the src/components/Hotjar directory.
Delete the relevant types off the appConfig type in the src/types/global.d.ts file.
Delete the <Hotjar ... /> component and its import from the src/root.tsx file.
Run vitest --run --update to update the snapshots.

Mixpanel integration

We use Mixpanel for analytics. You will need to create an account with them and set up a new project.

When you have your project set up, head to project settings and copy the Project Token and paste it set the MIXPANEL_TOKEN variable in the .env file.

Mixpanel allows you to choose the region where your data is stored. You can find the API endpoint for your region in the documentation.

You also need to set the MIXPANEL_API variable. This is the API endpoint that the stack will use to send events to Mixpanel. There is no default value to this because you should understand how you're dealing with data residency.

The values for the MIXPANEL_API variable are:

https://api-eu.mixpanel.com - for the European Union
https://api.mixpanel.com - for the rest of the world

You will also have to go to the variables settings and add the same variable names as the one in the .env file.

Warning The MIXPANEL_TOKEN and the MIXPANEL_API are set as a variable for the actions.

Removing the Mixpanel integration from the application

Delete the MIXPANEL_TOKEN and MIXPANEL_API variables from the .env file and GitHub variables.
Delete the src/components/Mixpanel directory.
Delete the relevant types off the appConfig type in the src/types/global.d.ts file.
Delete the <Mixpanel ... /> component and its import from the src/entry.client.tsx file.
Run vitest --run --update to update the snapshots.

Renovate bot setup

We use Renovate to manage dependency updates. To take advantage of it, you will need to install the Renovate GitHub App.

First, navigate to https://github.com/apps/renovate and click on the Install button.

On the following screen, we recommend selecting "All repositories" to make life easier, but you can configure it to only work on the repository you're currently in.

Sentry integration

Note Due to compatibility issues with Architect, the server-side instrumentation of Sentry is not working for now. Keep an eye on this issue for updates. The relevant code is commented out in the entry.server.tsx file.

We use Sentry for error reporting. You will need to create an account with them and set up a new project.

When you have your project set up, head to the project settings and copy the DSN and paste it set the SENTRY_DSN variable in the .env file.

You will also have to go to the variables settings and add the same variable name as the one in the .env file.

Next, head over to https://sentry.io/settings/account/api/auth-tokens/ and create a new token. You will need project:releases and project:read permissions.

Once you have the token, go to the secrets settings and add

SENTRY_AUTH_TOKEN - the token you just created
SENTRY_ORG - the organization slug
SENTRY_PROJECT - the project slug

We will be using these to send the source maps to Sentry so that the errors are properly mapped to the source code.

The deployment script will automatically upload the source maps to Sentry and then remove them locally, so they don't get uploaded to the environments.

How to find the DSN

First, Go to the project settings

Then on the sidebar, click on the Client Keys (DSN)

Finally, copy the DSN value

Removing the Sentry integration from the application

Delete the SENTRY_DSN variable from the .env file and GitHub variables.
Run npm remove @sentry/* to remove all the sentry packages.
Remove the sentryDsn from the appConfig and the SENTRY_DSN from the ProcessEnv type in the src/types/global.d.ts file.
On the very bottom of the src/root.tsx file, replace the withSentry(App) with App.
Remove the Sentry.init call from the src/entry.client.tsx and the src/entry.server.tsx files.
Follow the compilation and test errors to remove all the code that uses Sentry.
Open the .github/workflows/deploy.yml and the .github/workflows/ephemeralDeply.yml files and remove the Sentry Sourcemaps step.

Split integration

We use Split for feature flags. You will need to create an account with them and set up a new project.

When you have your project set up, head to the workspace settings > API Keys section. We're only interested in the server-side keys. Copy the API Key and paste it set the SPLIT_SERVER_TOKEN variable in the .env file.

For now, go to the Splits section on your workspace and set up 2 splits:

auth_enabled
hello_split

Make sure to click on them and add new targeting rules!

Go to the secrets settings and add the Auth0 secrets with the same name as the variables in the .env file.

Warning The SPLIT_SERVER_TOKEN is set as a secret for the actions.

Removing the Split integration from the application

Delete the SPLIT_SERVER_TOKEN variable from the .env file and GitHub secrets.
Delete the following files:
src/split.server.ts and the src/split.server.test.ts
src/feature.ts and the src/feature.test.ts
devFeatures.yml (from the project root)
Follow the compilation and test errors to remove all the code that uses the feature flags.
Run vitest --run --update to update the snapshots.

How to use ...?

This section dives deeper into the concepts present in the stack.

Authentication

The authentication is done via the auth0-remix-server package. The README file in that package has all the information you need to understand how it works.

Automated Semantic Versioning

We use Conventional Commits to automatically determine the next version of the package. It uses the semantic-release package to automate the versioning and release process.

The functionality is controlled by the .releaserc.json file. Since the projects that are created from this stack are most likely aren't going to be npm libraries, the npm publishing plugin is not included in the configuration.

To effectively use conventional commits, you need to understand the following basic principle:

Your commit messages determine if a new deployment happens to production.

Messages that trigger builds are:

fix: ... - fixes a bug
feat: ... - adds a new feature

Messages that don't trigger new versions (therefore builds) are:

docs: ... - changes to the documentation
chore: ... - changes to the build process or auxiliary tools and libraries such as documentation generation
refactor: ... - code changes that neither fixes a bug nor adds a feature
style: ... - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
test: ... - adding missing tests or correcting existing tests
ci: ... - changes to the CI configuration files and scripts
perf: ... - a code change that improves performance

Branching Strategy with Semantic Versioning

We will talk about how the deployment works in the Deployment section. For now, let's look at how the branching strategy works with the versioning.

There are 3 main branches:

main - this is the main branch. It is the branch that is deployed to production.
beta - this is the branch that is deployed to the beta (Staging) environment.
alpha - this is the branch that is deployed to the alpha (Staging) environment.

When you push to the main branch, a new version is released to production. The version is determined by the commit messages and every commit that is pushed to the main branch will trigger a new version.

When you push to the alpha or beta branch, a new Pre-release version is created. This allows you to iterate on features for an upcoming release and not worry about bumping the version number every time you push a commit that introduces a new feature or a fix.

For example, if you have a 1.0.0 version in production, and you push a commit to the alpha branch, the version will be 1.1.0-alpha.0. If you push another commit to the alpha branch, the version will be 1.1.0-alpha.1 and so on.

When you merge a pull request from the alpha or beta branch to the main branch, all the changes in those branches will be collected and bundled into a single release. To follow the example above, if you have a 1.0.0 version in production, and merge the alpha branch with its 1.1.0-alpha.1 version, your newly created version on production will be 1.1.0.

---
title: Branching & Versioning
---
%%{title: '', init: {'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}} }%%
gitGraph
    commit id: "v1.0.0"
    branch feature order: 2
    branch alpha order: 1
    checkout feature
    commit id: "fix: x"
    commit id: "fix: y"
    checkout alpha
    merge feature id: "v1.0.1-alpha.1"
    checkout feature
    commit id: "fix: z"
    checkout alpha
    merge feature id: "v1.0.1-alpha.2"
    checkout feature
    commit id: "feat: added something cool"
    commit id: "fix: fixed a mistake"
    commit id: "refactor: refactored the tests"
    checkout alpha
    merge feature id: "v1.1.0-alpha.1"
    checkout main
    merge alpha id: "v1.1.0"

Linting

We use commitlint to lint the commit messages. The configuration is in the package.json file. The linting happens whenever you make a commit. If the commit message doesn't follow the conventional commits format, the commit will fail.

The linting itself is triggered by lefthook

Which version am I running?

The version of the app is sent into the <html data-version="..."> attribute. You can use this to determine which version of the app is running on any given environment.

Dependency Version Updates

We use Renovate to automatically update the dependencies. The configuration is in the .github/renovate.json file.

By default, it is configured to update the dependencies according to some basic rules:

Runtime dependencies

Runtime dependencies are the dependencies section in the package.json file

Runtime dependencies are the libraries we use to run the application. This also means that security and bug fixes are important for these dependencies.

We want to update these dependencies as soon as possible, so we have the following configuration:

minor and patch versions - create a pull request with a fix: prefix in the commit message and merge automatically if possible
major versions - create a pull request with a fix: prefix in the commit message and do NOT merge automatically

Development dependencies

Development dependencies are the devDependencies section in the package.json file

Development dependencies are the libraries we use to develop the application. This means that we don't need to release a new version of the app when we update these dependencies.

We still want to update these dependencies as soon as possible, so we have the following configuration:

minor and patch versions - create a pull request with a chore: prefix in the commit message and merge automatically if possible
major versions - create a pull request with a chore: prefix in the commit message and do NOT merge automatically

Deployment

One of the main focuses of this stack was to create a deployment strategy that is a good starting point for anyone building from this stack.

We use a combination of GitHub Actions and AWS CDK to deploy the application to both the production-like and ephemeral environments.

Ephemeral Environments

Ephemeral environments are environments that are created on-demand and destroyed when they are no longer needed. We use these for feature branches and pull requests.

They are automatically created for pull requests, but you will have to manually trigger one if you just want to deploy a feature branch.

Manual Ephemeral Deployment

Navigate to https://github.com/meza/trance-stack/actions/workflows/ephemeralDeploy.yml and click the "Run workflow" button.

Once you have chosen a branch, it will start building the application and deploying it to the ephemeral environment.

When the process is finished, it will publish a summary to the run's Summary Dashboard with the link to the deployed application. It will look something like this:

Pull Request Ephemeral Deployment

When you create a pull request, GitHub Actions will automatically create an ephemeral environment for you and the deployment link will be added to the pull request as a comment.

Production-like Environments

Production-like environments are environments that are created once and then updated when the application is updated.

The branch main is considered to be the production branch while alpha and beta are considered to be staging.

This is decided in the deploy.yml file:

  build:
    environment: ${{ github.ref_name == 'main' && 'Production' || 'Staging' }}

The Production and Staging words here directly reference the GitHub Environments that we have configured.

Warning This means that both the alpha and beta branches will be deployed to the Staging environment.

This was done for convenience with the stack, but you are highly encouraged to change this to suit your needs. Maybe add a separate alpha environment?

Note Remember that the GitHub Environments hold the environment variables used for that given workflow. This means that you can set a different APP_URL for each environment among other things like a separate Auth0 tenant.

GitHub Actions

GitHub Actions respond to various events in the repository's lifecycle. The diagram below shows the flow of the deployment process.

flowchart TD
    F1 -.->|Manual Trigger| F

    subgraph Push
        A[Push] --> D{Is Protected Branch?}

        D -->|Yes| H{Is it the 'main' branch?}
        D -->|No| F1[Offer Manual Ephemeral Deployment]
        H -->|Yes| I1{{Deploy to Production}}
        H -->|No| I2{{Deploy to Staging}}

        I1 --> J1[Create GitHub Release]
        H -->|Yes| J2[Deploy Storybook]
        I2 --> J1
    end
    subgraph Pull Request
        B[Pull Request] --> F{{Ephemeral Deployment}}
    end

    subgraph Cleanup
        C[Delete Branch] --> X{{Destroy Deployment Stack}}
    end

The hexagonal nodes are processes which are executed by CDK while the others are handled with GitHub Actions.

CDK

AWS Cloud Development Kit (CDK) is an open-source software development framework to define cloud infrastructure in code and provision it through AWS CloudFormation.

Note If you are interested in why we chose CDK, check out the relevant ADR

The majority of the infrastructure is defined in the deployment directory. The deployment/lib directory contains the custom Constructs that are used to build the infrastructure.

Environment Variables

In order to deploy the application, you will need to set the following environment variables:

Variable	Secret	Description
	AWS_ACCESS_KEY_ID	The AWS access key ID used to deploy the application.
	AWS_CERT_ARN	The ARN of the certificate used for the domain.
	AWS_SECRET_ACCESS_KEY	The AWS secret access key used to deploy the application.
AWS_DOMAIN NAME		The final domain name of the application.
AWS_HOSTED_ZONE_NAME		The name of the hosted zone in Route53.

If you came here from the top of the document, go back to where you were and continue from there.

Local Environments

If you want to deploy the application locally, you will need to set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables only.

The deployment directory

The deployment/stacks directory contains the actual stacks that are deployed to AWS. Their naming should be self-explanatory. We have one for the Ephemeral environment and one for the Production environment.

If you examine either of the deployment files, you will notice that the deployment is basically a single command:

 npx cdk deploy remix-trance-stack-ephemeral -O /tmp/deployment.result.json \
 --require-approval never \
 --context environmentName=${{ env.REF_NAME }} \
 --context domainName=${{ vars.AWS_DOMAIN_NAME }} \
 --context certificateArn=${{ secrets.AWS_CERT_ARN }} \
 --context hostedZoneName=${{ vars.AWS_HOSTED_ZONE_NAME }}

The difference between the ephemeral and the production deployments is the name of the stack. It can be either remix-trance-stack-ephemeral or remix-trance-stack-production.

The context variables

The context variables are used to pass information to the CDK stack.

Variable	Description	Example
`environmentName`	The name of the environment. This is used to create derive the name of every single resource created on AWS.	feature1
`domainName`	The domain name of the application.	trance-stack.vsbmeza.com
`certificateArn`	The ARN of the certificate used for the application.	arn:aws:acm:region:123456789012:certificate/12345678-1234-1234-1234-123456789012
`hostedZoneName`	The name of the hosted zone used for the application.	vsbmeza.com

The domainName, certificateArn and hostedZoneName are only used for Production deployments.

Note Even though some context variables are only used for production deployments, they are still passed to the ephemeral deployment. This is because the CDK stack is the same for both environments and the evaluation of the context variables is done at runtime. For ephemeral deployments you can have an empty string for the domainName, certificateArn and hostedZoneName.

Deploying from your local machine

We advise you to use the GitHub Actions to deploy the application. However, if you want to deploy from your local machine, you can do so by running the same command as the deployment scripts would.

Warning Don't forget to run npm run build before deploying.

You can define the context variables either on the command line or you can use the cdk.context.json file.

{
  "environmentName": "localdev",
  "domainName": "trance-stack.example.com",
  "hostedZoneName": "example.com",
  "certificateArn": "arn:aws:acm:region:123456789012:certificate/12345678-1234-1234-1234-123456789012"
}

The githubActionSupport.ts file

Let's talk about the githubActionSupport.ts file.

This file uses the GitHub Actions toolkit to allow us to report back with the deployment URL to the GitHub Actions/Pull Request.

The reason it's a bit more complex than it needs to be is because we don't want to publish a PR comment every time we deploy the same branch. Since the URL won't change for a branch that's already deployed, there is no need to spam the PR.

This posed a challenge of finding an existing deployment comment and updating it instead of creating a new one.

Testing the GitHub support locally

If for whatever reason you would like to get a local output of the GitHub Actions support, you can do so by running the following command:

npx ts-node --prefer-ts-exts deployment/githubActionSupport.ts /tmp/deployment.result.json

This requires you to have a deployment.result.json file in the /tmp directory. You can get this file by running the deployment command locally.

The results will be added to the deploymentSummary.md file.

Environment variables

Environment variables are probably the biggest pain-point in the maintenance of this project. You have to add them to GitHub, add them to the deploy scripts and add them to the .env file.

We're working on a solution to this, but for now, you have to do it manually.

Adding a new environment variable checklist:

Add the variable to...

the .env file
the .env.example script. This is very important
the .github/workflows/deploy.yml script to the npm run build command
the .github/workflows/ephemeralDeploy.yml script to the npm run build command
the .github/workflows/ephemeralDestroy.yml script to the npm run build command
the .github/workflows/playwright.yml script to the Create Envfile section

Bundling environment variables

We bundle most of the environment variables into the server bundle. To understand why, read the relevant adr, and it's addendum.

The important thing to know is that what gets bundled is decided by reading the .env.example file and taking its keys.

You can prevent certain keys to get bundled by adding them to the deny list in the remix.config.js file.

  const doNotBundleEnv = [
  'APP_DOMAIN' // deny list for the environmentPlugin
]

Feature Flags

Feature flags are a fantastic way to test new features in production without having to worry about breaking anything. It enables you to decouple the release of new code from the release of new features. Read more

Let's look at an example which is in the src/routes/index.tsx file

export const loader: LoaderFunction = async ({ request, context }) => {
  const isAuth = await hasFeature(request, Features.AUTH);
  return json({
    isHelloEnabled: await hasFeature(request, Features.HELLO),
    isAuthEnabled: isAuth
  });
};

export default () => {
  const { isHelloEnabled, isAuthEnabled } = useLoaderData<typeof loader>();
  if (isHelloEnabled) {
    return (<div>
      <Hello/>
      {isAuthEnabled ? <Login/> : null}
    </div>);
  }
  return <div>Goodbye World!</div>;
};

Here all elements of the page are wrapped in a feature flag. The Hello component will only be rendered if the HELLO feature is enabled. The Login component will only be rendered if the AUTH feature is enabled.

Don't worry about using hasFeature a lot in your code. Split caches the results of the feature flags, so it's not a performance issue. Split works with streaming data and will check for changes in the feature flags every minute by default.

You can check all the available options in the Split documentation, and then set them as you wish in the src/split.server.ts file.

Before we continue, let's talk about the difference between production and local development.

Production

When you're running the application in production, the SPLIT_SERVER_TOKEN variable is set to the API key of your Split. You also need to manage all your flags (or splits as they're called in Split) in the Split Workspace dashboard.

Always use the Splits of your workspace as the source of truth.

The `features.ts` file

The features.ts file is a list of all the features that you have in your application. It's a good idea to keep this file in sync with the Splits in your workspace. This way you can easily see which features are available and which are not.

// src/features.ts
export enum Features {
  AUTH = 'auth_enabled', // the name of the split from the split.io workspace
  HELLO = 'hello_split'
}

Having this allows us to reference the features in our code without having to worry about typos.

Local development

When you're developing locally, you can set the SPLIT_SERVER_TOKEN variable to localhost. This sets split into a localhost mode, and it will use the devFeatures.yml file to determine if a feature is enabled or not. This file is located in the project root.

# devFeatures.yml

- auth_enabled:
    treatment: "on"
- hello_split:
    treatment: "on"

This file is a list of all the features that you have in your application. The treatment property determines if the feature is enabled or not. If the treatment is set to on, the feature is enabled. If it's set to off, the feature is disabled. Read more about treatments as they can be more than just on and off.

Warning Unfortunately, there is no simple way to keep the devFeatures.yml file, the src/features.ts final and the Splits in your split.io workspace in sync. You will have to do this manually.

I18N - Internationalization

We're using i18next for internationalization. You can read more about it in the i18next documentation. To integrate it with Remix, we're using the remix-i18next package and our setup is based on the remix-i18next Readme file.

You can find the i18n configuration in the src/i18n directory. The i18n.config.ts file contains the configuration for the defaults of i18next. The i18n.server.ts file contains the configuration for the server side while the i18n.client.ts file contains the configuration for the client side.

The only deviation we have from the remix-i18next sample setup is that we're actually bundling the translations into the server package. This is done in the src/i18n/i18n.server.ts file.

await i18nextInstance.init({
  debug: process.env.I18N_DEBUG === 'true',
  ...baseConfig,
  lng: locale,
  ns: remixI18next.getRouteNamespaces(remixContext),
  // The sample setup in remix-i18next
  //backend: {
  //  loadPath: resolve("./public/locales/{{lng}}/{{ns}}.json"),
  //},
  resources: {
    en: {
      translation: en
    }
  }
});

We're doing this because in the AWS Lambda environment, we have one single file as the handler, and it needs to be self-contained. While traditional lambda functions could have access to attached file systems, it would make deployments more complicated and the function would become incompatible with Lambda@Edge solutions.

Therefore, instead of using the fs-backend, we're directly importing the resources from the public/locales directory.

This does mean that when you add a new locale, you will have to add it to the resources in the i18n.server.ts file.

Using translations

To use translations in your application, you can use the useTranslation hook from the react-i18next package.

import { useTranslation } from 'react-i18next';

export const Hello = () => {
  const { t } = useTranslation();
  return (
    <h1 data-testid={'greeting'} className={'hello'}>{t('microcopy.helloWorld')}</h1>
  );
};

You can also pass in variables to the translations. This helps the translators to create more context-sensitive translations.

Take this example from the initial logged in Dashboard of the application:

export default () => {
  const { t } = useTranslation();
  const { user } = useLoaderData<typeof loader>();
  return (<>
    <div>{t('dashboard.for', { name: user.nickname || user.givenName || user.name })}<br/><Logout/></div>
  </>);
};

Here we pass in the name variable to the translation. This means that the location of where the name appears in the final text can be different in different languages. For example, in one context we could say "Dashboard for John!" and in another context we could say "John's dashboard!".

The translation file in our dashboard's case looks like this:

{
  "dashboard": {
    "for": "Dashboard for {{ name }}"
  }
}

Adding a new locale

To add a new locale, you will have to do the following:

Add the new locale to the public/locales folder. Follow the example of the existing locale(s)
Add the new locale to the resources object in the i18n.server.ts file.
Add the new locale to the supportedLngs array in the i18n.config.ts file.

Removing i18n from your project

If you don't want to use i18n, you can remove it from your project. You will have to do the following:

Remove the i18n folder from the src directory
Remove the locales folder from the public directory
Run npm remove i18next i18next* *i18next
Remove the <<I18nextProvider ...> from both the src/entry.server.tsx and src/entry.client.tsx files
Follow the compilation errors and remove any remaining references to i18n

Note

There are some great tips about organising your translations in the i18n Readme file.

Lefthook

The commit validation and the automatic dependency installation is done by Lefthook

The configuration file is at .lefthook.yml. You can see all the commands that happen and the git hooks they are attached to.

If running all the tests at every commit is too much, you can always set it to happen on pre-push instead.

NPMIgnore - automated

In case you would ever want to publish your project to NPM (which you shouldn't), you can use the npmignore package to automatically generate an .npmignore file. This file will be generated based on the .gitignore file.

There is a basic ignore configuration in the package.json file's publishConfig section.

Playwright - End-to-end testing

We use Playwright for our end-to-end tests. Playwright is a successor to Cypress and Puppeteer. It's maintained by Microsoft and is a cross-browser testing tool. It's also a lot faster than Cypress.

Learn more about Playwright here.

Installing Playwright dependencies

Playwright requires a few dependencies to be installed in order to run locally. You can install them by running the following command:

npx playwright install --with-deps

Configuring Playwright

The tests are located in the playwright/e2e directory. Feel free to change the directory structure to your liking. If you do so, don't forget to update the test location in the playwright.config.ts file.

export default defineConfig({
  testDir: './playwright/e2e', // <-- Update this

You do not need to start the dev server before running the tests.

Playwright will start the dev server for you. It is configured in the playwright.config.ts file right at the bottom:

  /* Run your local dev server before starting the tests */
webServer: {
  command: 'npm run dev',
    url
:
  'http://localhost:3000',
    timeout
:
  1 * 60 * 1000,
    reuseExistingServer
:
  !process.env.CI
}

Running the tests

Playwright on GitHub Actions

Every time you open a pull request to the main branch, the tests will be run on GitHub Actions.

Playwright locally

You can run the tests locally by running the following command:

npm run int

The reports will go to the reports/e2e directory.

Storybook

We use Storybook V7 with Webpack 5. Remix is still a bit behind in terms of Storybook support, so we had to do a few things to get it to work.

Warning Storybook 7 brings some fundamental changes to how Storybook works. It is HIGHLY encouraged that you read the migration guide to see what changed. Things that you are used to might not work the same way anymore.

There is an ongoing discussion within the Remix community about how to best solve this issue.

This code doesn't include the remixStub yet, but it might change soon.

If you know how to configure it properly, please open a PR.

Running Storybook

You can run Storybook by running the following command:

npm run storybook

If you're looking for inspiration on how to organise your stories, you can check out the Telekom Scale project

Publishing Storybook

Remember when we set up Pages at the beginning?

Storybook automatically gets published to GitHub Pages when you push to the main branch.

This is done via the .github/workflows/storybook.yml workflow.

Accessing the published Storybook

Right at the top of this README, you can see a badge linking to the published Storybook.

Styling / CSS

We use regular stylesheets in this project which means a combination of Shared Component Styles and Surfacing Styling.

Shared Component Styles

The shared component styles live in the src/styles directory. They are imported in the routes that use them.

// src/root.tsx
import styles from './styles/app.css';

export const links: LinksFunction = () => {
  return [
    { rel: 'stylesheet', href: styles }
  ];
};

The styles that are uniform across the entire application are loaded from the src/root.tsx file while the styles that are specific to a single route are loaded from the route itself.

These are all additive, so you can have a single stylesheet that is loaded on every route via the root.tsx, and then additional stylesheets that are loaded on specific routes.

If you need a component-specific stylesheet, you can use the Surfacing Styling method.

Surfacing Styling

To have local styles per component, we use is Surfacing Styling.

Because these are not routes, and therefore not associated with a URL segment, Remix doesn't know when to prefetch, load, or unload the styles. We need to "surface" the links up to the routes that use the components

This solution is a bit more complex, but it allows us to have styles that are only loaded when the component is loaded.

Take the Hello component as an example:

import { useTranslation } from 'react-i18next';
import styles from './hello.css';

export const links = () => [
  { rel: 'stylesheet', href: styles }
];

export const Hello = () => {
  const { t } = useTranslation();
  return (
    <h1 data-testid={'greeting'} className={'hello'}>{t('microcopy.helloWorld')}</h1>
  );
};

export default Hello;

Notice that it imports the hello.css file. This file is located in the same directory as the component. It also has a links export that returns the stylesheet link.

In Remix terms however, a component is not a route, so we need to "surface" the links up to the routes that use the components. You can see an example of this in the src/routes/index.tsx file:

import { Hello, links as helloLinks } from '~/components/Hello';

export const links: LinksFunction = () => ([
  ...helloLinks()
]);

We import the links export from the Hello component and add it to the links export of the index.tsx route.

Yes, this is more complicated than it should be but with the rapid development of Remix, we hope that this will be simplified in the future.

PostCSS

We use PostCSS to process CSS. Remix has a built-in PostCSS plugin that allows you to import CSS files directly into your components. Read more about how CSS in Remix works.

Our PostCSS configuration is located in the postcss.config.js file, and it gets applied every single time Remix builds the application. This means that you don't have to think about prefixes or other browser-specific CSS features. Just write your CSS and PostCSS will take care of the rest automagically.

Typescript Paths

We use Typescript Paths. This means that instead of messy relative paths in the imports, we can use handy aliases.

We have the following paths defined by default:

~ - the src folder
@styles - the src/styles folder
@test - the test folder

This means that no matter where you are in the file tree, you can always reference the src folder with the ~ alias.

import Hello from '~/components/Hello';
import appStyles from '@styles/app.css';
import { renderWithi18n } from '@test';

Feel free to add your own paths in the tsconfig.json file.

Common ones that you might want to add are:

@components - the src/components folder
@routes - the src/routes folder
@hooks - the src/hooks folder

We have chosen not to add those because ~/hooks and @hooks are not that different to warrant extra settings.

Issues with Typescript Paths

Unfortunately, typescript paths are somewhat esoteric and support across tools can be spotty.

Vitest

Vitest for example needs special configuration to handle it. You can find the configuration in the vitest.config.ts file. It both requires the vite-tsconfig-paths plugin and in some cases you need to manually add the path to the resolve.alias array.

// vite.config.ts
resolve: {
  alias: {
    '~'
  :
    path.resolve(__dirname, './src')
  }
}

Storybook

Storybook also needs to be told to respect the typescript paths. We use the tsconfig-paths-webpack-plugin to tell the storybook webpack config to respect the paths.

We add it to the webpackFinal function in the .storybook/main.ts file.

webpackFinal: async config => {
  config.plugins?.push(new DefinePlugin({
    __DEV__: process.env.NODE_ENV !== 'production'
  }));
  if (config.resolve) {
    config.resolve.plugins = config.resolve.plugins || [];
    config.resolve.plugins.push(new TsconfigPathsPlugin()); // <--- this line
  }
  return config;
}

Unit Testing

We use Vitest as the unit testing framework. If you're unfamiliar with Vitest, fear not, its interface is very similar to Jest and you will have no issues getting started.

The main configuration file of Vitest is located at vitest.config.ts.

There has been quite a few deliberate decisions made here, so let's go through them.

Globals: true

The globals are off by default but to get js-dom to work with vitest, they need to be on.

Test reporters

We use different reporters depending on the environment. In the CI environment, we output junit and cobertura reports which then get published to the GitHub Actions Summary or as a Pull Request comment. On your local machine, we use the html reporter for coverage and a default text reporter for the test results.

In both cases we also print out a textual representation of the coverage report.

All the test reporting goes into the reports directory.

Setup files

If you look closely, you can see that we have a setupFiles section which calls the vitest.setup.ts file. This file is responsible for setting up the environment for the tests. It installs the @testing-library/jest-dom package and sets up a universal afterEach hook to clean up after the tests.

This might not be to everyone's liking so feel free to change it. Just remember that if you remove the global afterEach hook, you will need to clean up after the tests yourself so make sure to run npm run ci and see what broke.

Since Remix relies on browser APIs such as fetch that are not natively available in Node.js you may find that your unit tests fail without these globals when running with some tools.

If you need to add more globals, you can do so in the vitest.setup.ts file.

Simply add:

import { installGlobals } from '@remix-run/node';

// This installs globals such as "fetch", "Response", "Request" and "Headers".
installGlobals();

Read about this more here;

Threads

While the promise of threads might sound appealing, switching them on drastically reduces the speed of vitest. This is a known issue, and we're waiting for it to be fixed.

Coverage

The stack comes with 100%+ coverage to cover edge cases. We know that this isn't everyone's cup of tea, so you can remove the statements, branches, lines and functions sections from the coverage configuration object if you want to.

Alternatively, you can modify the report script in the package.json file to remove the --coverage flag.

Development of the stack itself

Note

A note on lockfiles.

Since this is a "create" package, lockfiles are not included. This is to ensure that the latest versions of dependencies are used when creating a new project.

Name		Name	Last commit message	Last commit date
Latest commit History 583 Commits
.github		.github
.storybook		.storybook
deployment		deployment
docs		docs
playwright/e2e		playwright/e2e
public		public
remix.init		remix.init
server		server
src		src
testUtils		testUtils
types		types
.adr-dir		.adr-dir
.babelrc.json		.babelrc.json
.editorconfig		.editorconfig
.env.example		.env.example
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.releaserc.json		.releaserc.json
.stylelintrc.json		.stylelintrc.json
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FUNDING.yml		FUNDING.yml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
app.arc		app.arc
cdk.json		cdk.json
devFeatures.yml		devFeatures.yml
lefthook.yml		lefthook.yml
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.js		postcss.config.js
preferences.arc		preferences.arc
remix.config.js		remix.config.js
server.js		server.js
socket.yml		socket.yml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts

License

ecomized/trance-stack

Folders and files

Latest commit

History

Repository files navigation

TRANCE STACK

What's included

Using the stack

Quickstart

Notable npm scripts

Table Of Contents

Getting Started

Environment

GitHub Settings

Workflow permissions

Branch Protection

Pages

Environments

Variables vs. Secrets

GitHub Token - Do This First!

Setup for continuous deployment

Authentication with Auth0

Adding the Auth0 variables to GitHub

Enabling the Auth0 integration for feature branch/PR deployments

Removing the Auth0 integration from the application

CookieYes integration

Removing the CookieYes integration from the application

Google Analytics 4 integration

Removing the Google Analytics 4 integration from the application

Hotjar integration

Removing the Hotjar integration from the application

Mixpanel integration

Removing the Mixpanel integration from the application

Renovate bot setup

Sentry integration

How to find the DSN

Removing the Sentry integration from the application

Split integration

Removing the Split integration from the application

How to use ...?

Authentication

Automated Semantic Versioning

Branching Strategy with Semantic Versioning

Linting

Which version am I running?

Dependency Version Updates

Runtime dependencies

Development dependencies

Deployment

Ephemeral Environments

Manual Ephemeral Deployment

Pull Request Ephemeral Deployment

Production-like Environments

GitHub Actions

CDK

Environment Variables

Local Environments

The deployment directory

The context variables

Deploying from your local machine

The githubActionSupport.ts file

Testing the GitHub support locally

Environment variables

Adding a new environment variable checklist:

Bundling environment variables

Feature Flags

Production

The features.ts file

Local development

I18N - Internationalization

Using translations

Adding a new locale

Removing i18n from your project

Lefthook

NPMIgnore - automated

Playwright - End-to-end testing

Installing Playwright dependencies

Configuring Playwright

Running the tests

The `features.ts` file

Packages