# Bundle Management

Source: https://dev.arcxp.com/integrations/bundles/bundle-management/

This document will walk you through the workflow for bundling, deploying and promoting integrations.

Bundles are the zipped code that will run your integrations, and they function very much like PageBuilder and Themes bundles. They are built locally then uploaded to the server. When first uploaded they will be “unused”. Deploying a bundle makes it ready for use and it can be promoted to “live”. There can only be one promoted bundle at a time, and this is the code that will run when your integration is invoked.

Be sure to fully test your bundle’s code before deciding to promote it. If something happens to go wrong, you can quickly “roll back” by promoting the last-known working bundle. In the absence of a usable bundle, you have the option to disable your integration in case of an emergency.

## Bundle Status Terminology

The following table represents the status of a bundle associated with an integration:

| STATUS    | DESCRIPTION                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Unused    | The zipped bundle has been uploaded but is not deployed and cannot be promoted._Note that uploaded bundle names must be unique!_                       |
| Deploying | The bundle is actively being deployed. This process usually takes about 30-40s.                                                                        |
| Deployed  | The uploaded bundle is deployed to an environment so that it can be promoted, and the version of the bundle can be seen on the property deployVersion. |
| Promoting | The bundle is actively being promoted to “live”. This process usually takes about 10s.                                                                 |
| Live      | A deployed bundle is promoted as live and is being used by the integration, receiving live traffic.                                                    |

> **Test, test, test:**
> 
> Once you promote a bundle, test it thoroughly (especially in a production environment) to ensure all processes are working as expected.
> 
> If you encounter issues with a live bundle, you can quickly switch back to a previous version by clicking “Promote” on a deployed bundle in the UI, or by using the promote [API endpoint](#promote-a-bundle-to-live) and providing the bundle’s name.

## Build a Bundle Locally

The SDK expects a fairly rigid code structure for uploaded code, but as long as a few norms are followed bundling your integration will be painless.

### Pre-bundle Checklist

1. Run `npm install` to make sure you have everything your integration needs in the `/node_modules` directory
2. Ensure your integration code runs and has been linted. For your privacy and application security, IFX will not do any validation on your integration code.
3. Exclude any `devDependencies` and test code you do not want deployed

> **Tip:**
> 
> If you encounter issues with node modules, clear out any hiccups with `rm -rf node_modules` and then rerun `npm install`. If you still have an issue you may have to do more investigating.

### Bundle it Up!

“Bundle” is the term PageBuilder uses to denote a zip file, and in IFX we’ve coopted that term.

When you create a new integration, we provide a deployed starter package for you. This package includes the scripts needed to zip everything into the top of the directory `/dist`. These are not designed to be modified, but you can add your own if you’d like.

```js
"scripts": {
    "localTestingServer": "node node_modules/@arcxp/arcxp-ifx-node-sdk/localTestingServer",
    "prelocalTestingServer": "node node_modules/@arcxp/arcxp-ifx-node-sdk/eventsHandlersModuleGenerator",
    "postinstall": "npm run prelocalTestingServer",
    "clean": "rimraf dist/",
    "build": "npm run clean && cpy src/* .env.sandbox .env.production ./node_modules/ ./dist",
    "zip": "(cd dist/ && zip -r ../dist.zip ./* -x \"dist.zip\")"
 }
```

When you have tested your code and are ready to bundle your integration code:

1. Run `npm run build`. This will also help to catch most errors.  
    
After this has executed, the unzipped code is put into `/dist`:  
    
![IDE explorer view of code (files) after unzipping](https://dev.arcxp.com/images/ifx/after-build.png)
2. Zip it up with `npm run zip`
  
> If you are feeling like a rockstar, you can combine the two commands:  
> `npm run build && npm run zip`

#### Naming a Bundle

After running `npm run zip` there will be a zip file in the project root called `dist.zip`.

My personal preference is to rename this to represent my versions. For example, the last bundle I uploaded was called `gigi-v3.zip` so I run `mv dist.zip gigi-v4.zip`

> **Naming a bundle:**
> 
> When uploading, all bundle names must be unique.

#### Self-bundling

There may be cases where your integration is built in TypeScript or other supersets. This can be done but requires you to bundle your code a bit differently.

> For more information on supersets, see [Using TypeScript and Other JS Supersets in Integrations](https://dev.arcxp.com/integrations/how-to-guides/ifx-using-typescript-and-other-js-supersets/)

The end goal is to include:

1. The source code
2. Node modules directory
3. Any environment var files you want to include into the zip file

This can often be achieved by running

Terminal window

```bash
zip -r ../myzip.zip src/ node_modules/ env.sandbox .env.production
```

#### Error when running `npm run build`

If you get this error when building the bundle “_SyntaxError: Cannot use import statement outside a module_” and it is calling out something inside of `/node_modules`, run `rm -rf node_modules && npm install`

![console example of SyntaxError](https://dev.arcxp.com/images/ifx/syntax-error.png)

## Managing Integration Bundles

You can manage bundles using the [API](https://dev.arcxp.com/api/integrations/integrations-production/), the [IFX CLI](https://dev.arcxp.com/integrations/ifx-cli/) or the IFX UI.

### UI Bundle Management

To manage bundles through the UI, simply navigate to your Arc Home page and click on the IFX tile. This will display a list of all your integrations, allowing you to click on each one to view its details. Here you can also upload, deploy and promote the associated bundles.

### CLI Bundle Management

Navigate to the [IFX CLI page](https://dev.arcxp.com/integrations/ifx-cli/) for instructions on getting started.

### API Bundle Management

#### List an Integration’s Bundles

See a list of bundles and their [statuses](#bundle-status-terminology) associated with an integration.

Terminal window

```bash
GET /ifx/api/v1/admin/bundles/:integrationName
```

#### Upload a Bundle

In order for a bundle to be available for use you will need to upload it.

> **Reminder:**
> 
> Bundle names must be unique!

Once you have zipped up your code, use the [Upload API](https://dev.arcxp.com/api/integrations/integrations-production/) to make it available for deployment. Upon success, it will return the metadata of the newly uploaded bundle. **The maximum size is 100MB**.

Terminal window

```bash
curl -X POST \
 --location 'https://api.{:org}.arcpublishing.com/ifx/api/v1/admin/bundles/:integrationName' \
 --header 'Authorization: Bearer ' \
 -F 'name=myIntegration-1-1-0' \
 -F 'bundle=@/path/to/zip/myIntegration.zip;type=application/zip'
```

#### Download a Bundle

Download an integration’s bundle.

Terminal window

```bash
curl -L -o myIntegration.zip \
'https://api.{:org}.arcpublishing.com/ifx/api/v1/admin/bundles/:integrationName/download/:bundleName' \
--header 'Authorization: Bearer [token]'
```

#### Deploy a Bundle

An unused bundle means that it is uploaded to a server and ready to be used, but it has not yet been deployed. Use the [Deploy API](https://dev.arcxp.com/api/integrations/integrations-production/) to deploy an unused bundle and make it eligible for promotion to live.

Terminal window

```bash
POST /ifx/api/v1/admin/bundles/:integrationName/deploy/:bundleName
```

#### Promote a Bundle to Live

In order for a deployed bundle to go live and receive traffic on an environment, it must be promoted. Promoting a bundle is the same thing as a “release”.

Terminal window

```bash
POST /ifx/api/v1/admin/bundles/:integrationName/promote/:version
```

> **Test, test, test! (again):**
> 
> Once you promote a bundle, test it thoroughly (especially in a production environment) to ensure all processes are working as expected.
> 
> If you encounter issues with a live bundle, you can quickly switch back to a previous version by clicking “Promote” on a deployed bundle in the UI, or by using the promote [API endpoint](#promote-a-bundle-to-live) and providing the bundle’s name.

---
  
Have a feature request or suggestion? Let us know on [Our Ideas Portal](https://ideas.arcxp.com/?project=IFX).