-
/src/components(Will be bundled with Stencil): stencil web component, separate folder into 4 types:-
main: component that will receive custom configuration from users, do all of the script and css injection into consumer page and also control how other components will show/hide by using stencilstore. -
checkout: main components that will handle zonos checkout -
hello: main components that will handle zonos hello (currently holding the component placeholder) -
store: this is state management amongs all of the components. -
stripe: the folder that will hold all of the stripe wrapper web components -
utils: folders that will hold all of the necessary utilities for all of the components in stencil -
components.d.ts: generated typed component that will have global types for all web components
-
-
/src/scripts(Will be bundled with regular rollup): scripts that will be bundled into cdn and init global utility function when consumer inject cdn into their page. Consumer then can use to init zonos elements.-
/src/scripts/demo: base scripts for the demo.setup.tsis for how to setup configuration andcustomer-site-interaction.tsis just base interaction for website (add to cart behavior).
-
-
/src/styled: folder that will hold all of the styling related for all web components-
variables: scss variables that will be used throughout the web components application (better to just have scss variables and should not have css) -
css: folder that will hold all of the global css (this will be generated and inject into<head>consumer site)
-
- Have environment
t3setup, but currently it's only being used inrollupandstencilconfig for build time checking. It may be will remove this in the future if we don't have any severless api or api using related (right now using just nativeprocess.env, and have the rollup env plugin to transfer that env into actual value when building. - separate tsconfig for each bundling:
-
tsconfig: will include all folders to have all of the intellisense throughout the project. -
tsconfig.build: stencil building process -
tsconfig.demo-script: script for demo script -
tsconfig.scripts: rollup bundling for loading script.
-
IMPORTANT: Be careful when updating the API. Changes, such as modifications to the API path or parameter requirements (like field name changes or making parameters optional or mandatory), could disrupt older versions of zonos-elements. To prevent this, consider keeping the existing endpoint and introducing a new one with the updates. This approach applies to both endpoint path changes and parameter updates. Gradually phase out the old endpoint once all lower CDN versions have migrated.
In our demo-app, we treat the API as version-less because it relies on other components (like the customer-graph and front-end graph), and GraphQL does not offer a straightforward method to version queries and mutations. Given this, versioning our API currently seems unnecessary. However, we've devised a strategy for deprecating APIs, acknowledging that it might not be the optimal solution available:
- Changing Endpoint Paths:
- When an endpoint's path changes, we recommend a structured approach to mark the old endpoint as deprecated:
- Create a
(deprecated)folder next to the updated endpoint's directory. - Within
(deprecated), create a subfolder named after the current version on the main branch. - Move the original endpoint's directory to this new version-named folder.
Ex: If we update the endpoint from
/api/zonos-elements/calculate-landed-costto/api/zonos-elements/calculate-super-landed-cost, the directory structure would look like this:
- Create a
└── zonos-elements ├── (deprecated) │ └── (v1.2.3) │ └── calculate-landed-cost │ ├── CalculateLandedCost.graphql.customer.ts │ ├── FulfillmentCenters.graphql.customer.ts │ └── route.ts ├── calculate-super-landed-cost │ ├── CalculateLandedCost.graphql.customer.ts │ ├── FulfillmentCenters.graphql.customer.ts │ └── route.ts- This folder can be removed once no stores are using a version at or below the deprecated version.
- When an endpoint's path changes, we recommend a structured approach to mark the old endpoint as deprecated:
- Parameter requirement changes (optional, mandatory and removal) and API response structure changes
- For changes in parameter requirements (whether making them optional, mandatory, or removing them), follow these steps:
- Create a new markdown file named after the
current version on the main branchwithin the endpoint's directory. - In this markdown file, detail the changes required, such as fields becoming optional, mandatory, or being removed.
Note: When updating endpoint responses, it is okay to add new return fields, but removing fields (update mutation/query returns) may cause issues if an old version is expecting and using that old field from the response Ex:
- Create a new markdown file named after the
In└── zonos-elements ├── calculate-super-landed-cost │ ├── CalculateLandedCost.graphql.customer.ts │ ├── FulfillmentCenters.graphql.customer.ts │ ├── v1.2.3.md │ └── route.tsv1.2.3.md, you might have:--- + Keep and make `storeId` optional, and add `zonosStoreId` (Change field name `storeId` to `zonosStoreId`) + Make the `storeId` to accept both type `string` and `number` (Change field type of `storeId` from `string` to `number`) + Make the field `storeSetting` optional (Remove `storeSetting` field)- Update the current (non-deprecated) endpoint based on the notes in the
.mdfile when all stores have moved past the deprecated version and remove that file when all are done. Ex:- For file changes, if the changes made were:
- Change field type
storeIdfromstringtonumber==> takestringoff of the union type (string | number), just leavenumber. - Change field name
storeIdtozonosStoreId==> deletestoreIdfield. - Remove
storeSetting==> remove the optional fieldstoreSetting.
- Change field type
- For file changes, if the changes made were:
- For changes in parameter requirements (whether making them optional, mandatory, or removing them), follow these steps:
The github action would bump the version conditionally on qa and main branch merged event.
- qa branch merge flow: Only bump, publish version and create CDN when the version has alpha word.
- main branch merge flow: Create a branch against qa and run pnpm version:[patch|major|minor], have it merged to qa, it would not trigger the publish version and create CDN until the changes on qa get merged to main.
- Each PR against qa will need to be prerelease pumped by running pnpm version:alpha.
- PR get merged to qa will trigger the github action to publish to npm with alpha tag and create a cdn domain alpha.js.zonos.com - alpha cdn doesn’t need to be versioned, so that when rolling back, the changes will be affected right away.
- The release process would happen on qa. If we want to release, a new branch named build/v1.x.x will need to be checkout from qa. Bump the version (major, minor or patch), and then merge to qa.
- Create a new branch with the same name build/v1.x.xoff of main, pull from qa and just create PR and merge to main.
- PR get merged to
mainwill trigger the github action to publish to npm with major, minor or patch tag and create a cdn domain v1.2.3.js.zonos.com.
Below is scenario when to bump version:
- Alpha:
- If you need to have types change in zonos-elements and want to use that types in the dashboard (for example: add a new function into instance Zonos). Bump alpha would result pushing new version to npm, then dashboard can install and use it.
- If we want to have a domain with pinned version to use (v1.2.3-alpha.1.js.zonos.com) and not gonna be used directly with major pin domain (v1.js.zonos.com) Note: If you merge changes with alpha version to main, new release domain will not be generated.
- Patch:
- Any bug fix and small api changes
- Minor:
- Architecture changes but doesn't take too much effort to move store to newer version
- Big API refactor
- Major:
- A lot of stores are using zonos-elements stably and have new breaking changes would lead to breaking chain for all stores