Before you start
The README on main branch may contain some unreleased changes.
Go to release/latest branch to see the actual README for the latest version from NPM.
Navigation
Installation
NPM:
npm install @release-kit/client-dynamic-envYarn:
yarn add @release-kit/client-dynamic-envUsage
Dynamically insert env
Add to your Docker entrypoint script:
# will also use .env.production and .env.production.local
export CDE_ENV="production"
# will use .env files located in apps/client directory
export CDE_ENV_DIR="apps/client"
# will take only envs prefixed with VITE_
export CDE_ENV_PREFIX="VITE_"
# will insert filtered envs into /client/dist/index.html file
export CDE_DESTINATION="/client/dist/index.html"
# will replace {{ ENV }} with filtered envs base64 string
export CDE_SLOT="{{ ENV }}"
source <(wget -qO- https://raw.githubusercontent.com/release-kit/client-dynamic-env/main/scripts/insert.sh)The scripts loads .env files using the following order:
-
.env(lowest priority) .env.$CDE_ENV.env.$CDE_ENV.local-
.env.local(highest priority)
Environment variables are always expanded, so you can reuse them.
Extract env on client
Assume we have the following in our index.html:
<head>
<script>
window.env = '{{ ENV }}'
</script>
</head>We can extract env from window.env in production, and from import.meta.env / process.env in development:
import { extractEnv } from '@release-kit/client-dynamic-env'
export const env = extractEnv({
env: import.meta.env.DEV ? 'development' : 'production',
developmentEnv: import.meta.env,
productionSource: window.env,
validate: (env) => {
if (!env.VITE_API_URL) throw new Error('No VITE_API_URL specified')
return { apiUrl: env.VITE_API_URL }
},
})Contributing
- Fork this repo
- Use the Regular flow
Please follow Conventions
Maintenance
The dev branch is main - any developer changes is merged in there.
Also, there is a release/latest branch. It always contains the actual source code for release published with latest tag.
All changes is made using Pull Requests - push is forbidden. PR can be merged only after successfull test-and-build workflow checks.
When PR is merged, release-drafter workflow creates/updates a draft release. The changelog is built from the merged branch scope (feat, fix, etc) and PR title. When release is ready - we publish the draft.
Then, the release workflow handles everything:
- It runs tests, builds a package, and publishes it
- It synchronizes released tag with
release/latestbranch
Regular flow
- Create feature branch
- Make changes in your feature branch and commit
- Create a Pull Request from your feature branch to
main
The PR is needed to test the code before pushing to release branch - If your PR contains breaking changes, don't forget to put a
BREAKING CHANGESlabel - Merge the PR in
main - All done! Now you have a drafted release - just publish it when ready
Prerelease flow
- Assume your prerelease tag is
beta - Create
release/betabranch - Create feature branch
- Make changes in your feature branch and commit
- Create a Pull Request from your feature branch to
release/beta
The PR is needed to test the code before pushing to release branch - Create Github release with tag like
v1.0.0-beta, pointing torelease/betabranch
For nextbetaversions use semver build syntax:v1.0.0-beta+1 - After that, the
releaseworkflow will publish your package with thebetatag - When the
betaversion is ready to becomelatest- create a Pull Request fromrelease/betatomainbranch - Continue from the Regular flow's #5 step
Conventions
Feature branches:
- Should start with
feat/,fix/,docs/,refactor/, and etc., depending on the changes you want to propose (see pr-labeler.yml for a full list of scopes)
Commits:
- Should follow the Conventional Commits specification
- You can find supported types and scopes into
.cz-config.js
Pull requests:
- Should have human-readable name, for example: "Add a TODO list feature"
- Should describe changes
- Should have correct labels