{"id":20188090,"url":"https://github.com/jnisperuza/custom-checkout-app","last_synced_at":"2025-04-10T06:44:41.067Z","repository":{"id":59165842,"uuid":"445418934","full_name":"jnisperuza/custom-checkout-app","owner":"jnisperuza","description":"The custom checkout app is a React app responsible for overwriting vtex native Checkout v6 editing and deploying files through the admin's interface. This project allows you to customize the native VTEX checkout, generating the files that you can later replace from the administration console of your VTEX store. https://{accountName}.myvtex.com/admin/portal/#/sites/default/code. Through a proxy software you can map the local files with which you can see the changes you make in development mode before updating your store's checkout. [Checkout UI Custom app, Checkout Customizer]","archived":false,"fork":false,"pushed_at":"2023-08-21T15:26:35.000Z","size":2806,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T07:52:39.959Z","etag":null,"topics":["checkout","checkout-customizer","checkout-react","checkout-ui-custom-app","checkout-ui-settings","custom-checkout-app","react-axios","react-css-module","react-jest","react-material-ui","react-redux","react-sass","react-webpack","scss","vtex","vtex-apps","vtex-checkout-deploy-app","vtex-deploy","vtex-react-checkout","vtex-react-checkout-app"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jnisperuza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-07T06:16:37.000Z","updated_at":"2024-05-27T11:28:13.000Z","dependencies_parsed_at":"2024-11-14T03:41:19.660Z","dependency_job_id":null,"html_url":"https://github.com/jnisperuza/custom-checkout-app","commit_stats":null,"previous_names":[],"tags_count":1,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnisperuza%2Fcustom-checkout-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnisperuza%2Fcustom-checkout-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnisperuza%2Fcustom-checkout-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnisperuza%2Fcustom-checkout-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jnisperuza","download_url":"https://codeload.github.com/jnisperuza/custom-checkout-app/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248173826,"owners_count":21059595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checkout","checkout-customizer","checkout-react","checkout-ui-custom-app","checkout-ui-settings","custom-checkout-app","react-axios","react-css-module","react-jest","react-material-ui","react-redux","react-sass","react-webpack","scss","vtex","vtex-apps","vtex-checkout-deploy-app","vtex-deploy","vtex-react-checkout","vtex-react-checkout-app"],"created_at":"2024-11-14T03:27:32.917Z","updated_at":"2025-04-10T06:44:41.032Z","avatar_url":"https://github.com/jnisperuza.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Custom Checkout App 🎨\n\nThe *custom checkout app* is a React app responsible for overwriting vtex native **[Checkout v6](https://help.vtex.com/tutorial/enable-checkout-v6--7qVqv3ptRvpVVplrvg8ruH)** editing and deploying files through the admin's interface.\nThis project allows you to customize the native VTEX checkout, generating the files that you can later replace from the administration console of your VTEX store. `https://{accountName}.myvtex.com/admin/portal/#/sites/default/code`.\nThrough a proxy software you can map the local files with which you can see the changes you make in development mode before updating your store's checkout. [Checkout UI Custom app, Checkout Customizer]\n\nFrom the scope of the VTEX checkout you have access to the following objects:\n\n**Important**: To use the vtexjs global variable from TypeScript files, it is recommended to declare this variable inside the component, to avoid linter errors.\n\n```javascript\ndeclare let vtexjs: any;\n```\n\n```javascript\nvtexjs.checkout.getOrderForm().then((orderForm) =\u003e {});\n```\n\n```javascript\nconst item = {\n    id: 1001,\n    quantity: 1,\n    seller: '1',\n};\n\nvtexjs.checkout.addToCart([item], null, 1).then((orderForm) =\u003e {});\n```\n\n```javascript\nvtexjs.checkout.setCustomData({});\n```\n\n```javascript\nvtexjs.checkout.removeItems([{ index, quantity: 0 }]);\n```\n\n```javascript\nvtexjs.checkout.removeAllItems(orderForm.items).then((orderForm) =\u003e {});\n```\n\n```javascript\nvtexjs.checkout.sendAttachment('KEY_NAME', {});\n```\n\n## Checkout confirmation page\n\nThis page consumes the data of the request through a queryParam called og to display it in the default template, to directly access the data you can do it by reading the global variable:\n\n```javascript\ndataLayer\n```\n\nHowever, you can also consult the data of the order from the following official vtex endpoint\n[Get Order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-)\n\n## Libraries with global Scope\n\nFrom the browser console you can type $ or Jquery and for underscore _ and you will be able to see the instances of the respective libraries.\n\n- JQuery\n- Underscore\n\n## Routes\n\n| Path    | Description    |\n| ------------ | --------------- |\n| `/#/cart`      | Shows the information of the products found in the orderForm. |\n| `/#/email`      | Is only shown when the orderForm does not have an active session, so it requests the email to check if the user already exists. |\n| `/#/profile`      | Request user information in case of being a user who is not yet registered. |\n| `/#/shipping`      | Request location information to determine logistics. |\n| `/#/payment`      | Allows you to select payment and billing methods. |\n| `/orderPlaced/?og=###`      | This route shows the information corresponding to the purchase with their respective codes for order tracking. **Important**: The vtexjs variable is not available in this path. |\n\n## Available Scripts ⚡\n\nIn the project directory, you can run:\n\n### `Build`\n\nBuilds the app for production to the `dist` folder.\\\nIt correctly bundles React in production mode and optimizes the build for the best performance.\n\n***Command available with `:dev`, `:qa`, and `:prod`***\n\n```bash\nnpm run build\n```\n\n### `Start`\n\nIt works in the same way as build but additionally while you are modifying, It generating new files for the `dist` folder.\n\n***Command available with `:dev`, `:qa`, and `:prod`***\n\n```bash\nnpm run start\n```\n\n### `Test`\n\nThis runs the tests contained in the `__test__` folder.\n\n```bash\nnpm run test\n```\n\n### `Launch Deploy App`\n\nInitializes a local server on port 9000, it can be accessed as follows \u003chttp://localhost:9000/\u003e. From here you can deploy your code. You just need to copy the vtex admin cookie header and paste it into the \"Cookie\" field.\n\n***Command available with `:dev`, `:qa`, and `:prod`***\n\n```bash\nnpm run deployapp\n```\n\n## Environments\n\nInside the \"environments\" folder you can find the configuration files .dev.env, .qa.env, .prod.env, there you can add your environment variables.\\\nWith the previous commands and the command `:dev`, `:qa`, and `:prod` for instance:\n\n```bash\nnpm run start:dev\n```\n\n***If you don't set environment, dev is taken by default value***\n\n## Project structure\n\n```bash\nsrc/\n.\n├── HOC\n│   └── ProviderContext\n│       └── index.tsx\n├── __test__\n│   ├── SampleToast.test.tsx\n│   └── __snapshots__\n│       └── SampleToast.test.tsx.snap\n├── axiosInstance.ts\n├── components\n│   ├── App\n│   │   └── index.tsx\n│   ├── Cart\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── CartLinks\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── CartMoreOptions\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── CartTemplate\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── ClientProfileData\n│   │   ├── ClientForm\n│   │   │   ├── index.tsx\n│   │   │   └── styles.scss\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── ConfirmationPage\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── Footer\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── Header\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── HtmlTooltip\n│   │   └── index.tsx\n│   ├── Layout\n│   │   ├── Layout.module.scss\n│   │   └── index.tsx\n│   ├── PaymentData\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── Preloader\n│   │   ├── Preloader.module.scss\n│   │   └── index.tsx\n│   ├── SampleDialog\n│   │   ├── SampleDialog.module.scss\n│   │   └── index.tsx\n│   ├── SampleLogo\n│   │   ├── SampleLogo.module.scss\n│   │   └── index.tsx\n│   ├── SampleToast\n│   │   ├── SampleToast.module.scss\n│   │   └── index.tsx\n│   ├── ShippingData\n│   │   ├── index.tsx\n│   │   └── styles.scss\n│   ├── StyledDialog\n│   │   ├── StyledDialogTitle\n│   │   │   ├── index.tsx\n│   │   │   └── styles.scss\n│   │   └── index.tsx\n│   └── Totalizers\n│       ├── index.tsx\n│       └── styles.scss\n├── constants.ts\n├── country\n│   └── COL.ts\n├── environment.ts\n├── helpers.tsx\n├── index.tsx\n├── redux\n│   ├── UI\n│   │   ├── action.ts\n│   │   ├── actionTypes.ts\n│   │   ├── reducer.ts\n│   │   └── selectors.ts\n│   ├── reducer.ts\n│   └── store.ts\n├── styles\n│   ├── _classes.scss\n│   ├── _fonts.scss\n│   ├── _mixins.scss\n│   ├── _variables.scss\n│   └── index.scss\n├── theme.ts\n└── types\n    └── orderForm.d.ts\n```\n\n## The files that you must add to the checkout from the VTEX administrator are\n\nThe same js and css files should be assigned to the content of the confirmation page files:\n\n- checkout-confirmation-footer\n- checkout-confirmation-header\n\n```bash\ndist/\n.\n├── checkout-confirmation4-custom.css\n├── checkout-confirmation4-custom.css.map\n├── checkout-confirmation4-custom.js\n├── checkout-confirmation4-custom.js.LICENSE.txt\n├── checkout-confirmation4-custom.js.map\n├── checkout6-custom.css\n├── checkout6-custom.css.map\n├── checkout6-custom.js\n├── checkout6-custom.js.LICENSE.txt\n├── checkout6-custom.js.map\n└── index.html\n```\n\n## Guide components 🍕\n\nTo explain how this checkout application works, the following components with which you can expand the rest of the sections and functionalities of the \"Custom checkout app\" application.\n\n### Client profile data\n\n```bash\n│   ├── ClientProfileData\n│   │   ├── ClientForm\n│   │   │   ├── index.tsx\n│   │   │   └── styles.scss\n│   │   ├── index.tsx\n│   │   └── styles.scss\n```\n\n![Client profile data empty](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/sample-1.png)\n\n![Client profile data fill](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/sample-2.png)\n\n### Toast\n\n```bash\n│   ├── SampleToast\n│   │   ├── SampleToast.module.scss\n│   │   └── index.tsx\n```\n\n![Toast](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/sample-3.png)\n\n### Dialog\n\n```bash\n│   ├── StyledDialog\n│   │   ├── StyledDialogTitle\n│   │   │   ├── index.tsx\n│   │   │   └── styles.scss\n│   │   └── index.tsx\n```\n\n![Dialog](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/sample-4.png)\n\n### Logo\n\n```bash\n│   ├── SampleLogo\n│   │   ├── SampleLogo.module.scss\n│   │   └── index.tsx\n```\n\n![Logo](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/sample-5.png)\n\n## Debug changes locally with Charles proxy 💻\n\nTo debug local changes you can use charles proxy as an option, below I show an example to map local files from charles proxy application.\n\n*As a help we leave you a general configuration guide of the application, keep in mind that it can change depending on the version you have of the application and also the operating system [Charles proxy settings](https://github.com/jnisperuza/custom-checkout-app/blob/main/assets/doc/charles-settings.pdf)*\n\n### Right click over the file what you want to map\n\n![Mapping local files](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/charles-1.png)\n\n### Select from your \"Local path\" the folder \"dist\" and choose the same file name you want to map\n\n![Mapping local files](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/charles-2.png)\n\n### As a final result you will have the files mapped and without any type of error or question symbol\n\n![Mapping local files](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/charles-3.png)\n\n## Deploy Checkout App ☁️\n\nBefore you run the `Deploy App` you must ensure updated environment file with you own trade policy in the property\n\n```bash\nREACT_APP_ENVIRONMENTS_URL: [{\"name\": \"myvtex\",\"value\": \"https://{accountName}.myvtex.com/admin/portal/#/sites/{devName}/code\"}]\n```\n\nOther important aspect is that this application needs a Vtex admin cookie as input, to choose an environment and click the \"Submit\" button.\n\n### ***Steps to get the Vtex Administrator Cookie***\n\nThere're multiple ways to get the cookie value, but only we'll mention two of them:\n\n#### The first option:\n\n1. Login to Vtex\n\n    ![Login to vtex](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/login-to-vtex.png)\n\n2. In the side menu look for the ***`STORE SETTINGS`*** and click on the option ***`Checkout`*** and then click on the engine icon\n\n    ![Click on checkout option](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/click-on-checkout-option.png)\n\n3. On the next view, you should click ***`Code`***\n\n    ![Click on code tab](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/click-on-code-tab.png)\n\n4. In this section you need to edit some file to get the cookie from the request as shown in the following image\n\n    ![Edit some file](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/edit-some-file.png)\n\n    ![Edit some file](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/copy-cookie-header.png)\n\n![Deploy app Option 1](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/deploy-checkout-app.png)\n\n#### The second one\n\nIf you use [Google Chrome](https://chrome.google.com/webstore/detail/editthiscookie/fngmhnnpilhplaeedifhccceomclgfbg?hl=en) or [Opera](https://addons.opera.com/en/extensions/details/edit-this-cookie/) as a main browser, you could install an extension like a [EditThisCookie](https://www.editthiscookie.com/).\n\n- Open extension once you've had logged into de Vtex administrator and copy value:\n\n    ![Open extension EditThisCookie](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/EditThisCookie.png)\n\n![Deploy app Option 2](https://cdn.statically.io/gh/jnisperuza/custom-checkout-app/main/assets/images/deploy-app.png)\n\n***`IMPORTANT`*** limit of size each file: 3Mb\n\n## Learn More 🛠️\n\n- [React](https://react.dev/reference/react)\n- [Webpack](https://webpack.js.org/configuration)\n- [Sass](https://sass-lang.com)\n- [Babel](https://github.com/babel/babel-loader)\n- [Axios](https://github.com/axios/axios)\n- [Material UI](https://mui.com)\n- [Notistack](https://notistack.com/getting-started)\n- [Charles Proxy](https://www.charlesproxy.com/documentation/using-charles)\n- [Checkout Vtex](https://github.com/vtex/vtex.js/blob/master/docs/checkout/README.en.md)\n- [OrderForm Custom Data](https://developers.vtex.com/docs/guides/add-and-handle-custom-information-in-the-order)\n- [Update orderForm configuration](https://developers.vtex.com/vtex-developer-docs/reference/updateorderformconfiguration)\n- [Add client profile](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/clientProfileData)\n- [CMS - Creating and editing a page template](https://help.vtex.com/tutorial/how-to-create-a-page-template--frequentlyAskedQuestions_1850)\n- [Checkout customization guide](https://developers.vtex.com/vtex-rest-api/docs/checkout-customization-guide)\n- [Customizing the Checkout Confirmation pages](https://developers.vtex.com/docs/guides/customize-checkout-confirmation-pages)\n\n## Author ✒️\n\n- **Jeison Nisperuza** - [jnisperuza](https://github.com/jnisperuza) - [jnisperuza.github.io](https://jnisperuza.github.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnisperuza%2Fcustom-checkout-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjnisperuza%2Fcustom-checkout-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnisperuza%2Fcustom-checkout-app/lists"}