Application Structure

ShipEngine Connect applications are just NPM packages that meet the following requirements:

  • Have a package.json file in the root directory, which specifies its name, version number, and dependencies.

  • Have the @shipengine/connect package as a dependency or devDependency in the package.json file.

  • Export an object with properties and methods that define the app's capabilities and functionality. This must be the main export of the NPM package.

Other than that, everything else is up to you. We don't impose any specific folder structure or file naming convention. You can build your app just as you would build any other NPM package.

Getting Started

The ShipEngine Connect CLI makes it easy to get started with your app. It comes with built-in templates for each app type. Just run the connect init command, answer a few questions, and it'll create all the files and pre-populate much of the basic scaffolding for you.

For more details, see Creating Your First App.

Application Definition

The main export of your app's NPM package must be an object that defines your app's capabilities and functionality. The properties and methods of this object depend on the type of app you're building.

To make things even easier for you, your Application Definition object can be a JSON, JSON5, YAML, or TypeScript file in addition to plain JavaScript. You can even split your app definition into many separate files if you want, and each file can be any of these file types. You'll make this the main export by setting the main property of your package.json file to the path to your application definition file.

Example

Here's an example of a Carrier Application Definition that consists of multiple files in multiple formats. The main file is in YAML format, each of the methods are in separate JavaScript files, the connectionForm and settingsForm are in separate JSON files, and each of the deliveryServices is in a separate YAML file.

id: 55906eb1-8e2b-432a-81e7-53103bfc2886
name: Cargo Incorporated
description: Cargo Incorporated is the global leader in air cargo.
websiteURL: https://cargo-inc.net
logo: logo.svg
icon: icon.svg
connect: src/connect.js
createShipment: src/create-shipment.js
trackShipment: src/track-shipment.js
connectionForm: forms/connect.json
settingsForm: forms/settings.json
deliveryServices:
  - delivery-services/standard.yaml
  - delivery-services/economy.yaml
  - delivery-services/overnight.yaml

For more complete examples, see our complete sample apps.

Methods

As mentioned above, the main export of your application package must be an Application Definition object, which has properties and methods. The properties define your app's capabilities and features, but the methods provide your app's actual implementation, such as logging in, creating a shipment, or retrieving shipping rates. As you can imagine, the methods are probably where you'll spend most of your time when building an app.

Methods are just JavaScript functions that take input from ShipEngine Connect and return results to the platform. What happens in-between those two is entirely up to you. But, in general, most methods will consist of the following steps:

1) Transform the input data into whatever structure is needed by your API.

2) Call your API(s) to perform whatever operations are necessary and/or to retrieve whatever data was requested.

3) Transform the data from your API into the structure that's needed by ShipEngine Connect.

4) Return the data.

Forms

Forms are used gather data from an end-user that is interacting with your application from within on of our e-commerce applications. For example, you will need to supply a connection form that gathers login credentials from the end user so they can be authenticated with your API. In the example above, you can see that the path to the connectionForm is specified in the app definition.

Definitions

In addition to the application definition, some application types, such as the Carrier app, include definition files for the services it provides. For example, each type of delivery service offered by a Carrier app will be described by a Delivery Service Definition file. In the application definition above, you can see these definition files referenced in the deliveryServices array.

Previous: Getting StartedNext: Recommended Tools