Creating Your First App

ShipEngine Connect CLI provides you with everything you need to get started with your integration application.

Using the CLI

  1. To create a new project, open a terminal on your computer and navigate to the directory where you would like to add your new project by running the following command: cd my-project-directory

  2. Run the following command: connect init

  3. Enter the npm package name you would like to give your application. The default value is the name of the directory in which you ran the command. Type a new value for the name or press Enter to accept the default name.

  4. Use the arrow keys to select which app type you'd like to create, then press Enter.

  5. Enter a description for your application, and press Enter.

  6. Enter a value to be used in the author property of your package.json file. If you are logged into GitHub in the terminal from which you ran the command, your GitHub user information will be populated as the default. Type a new author value, or press Enter to accept the default.

  7. Enter a value to be used in the version property of your package.json file. This value defaults to 1.0.0. Press Enter to accept the default value, and then increment this property in your package.json file anytime you publish your application.

  8. Use the arrow keys to select either JavaScript or TypeScript as your language and press Enter.

cli-screenshot

Your Application

All done! You now have the application structure laid out, and you are ready to provide the implementation.

Methods

In the src/methods directory, you will find a file for each method that can be implemented by the application type you selected. Each file contains a stubbed out method in the language you specified when you ran the command. It contains comments to remind you of the steps required to implement each method. You aren't required to maintain this directory structure. You can choose to implement all your methods in one file or choose a different directory structure. As long as your application definition specifies the path to a file that exports the method, the structure is up to you.

Definitions

In the src/definitions directory, you will find a sample file with the required properties for each type of definition you can provide for your application. For example, in a Carrier Application, you may provide one or more definitions for the following: delivery service, delivery confirmation, and packaging.

As with methods, you aren't required to maintain this directory structure. As long as your application definition specifies the correct paths to the definitions you want to include, you can organize your files however you'd like. In addition to the definitions for the services that are offered, running this command creates a sample application definition as well. It uses the values you provided when you ran the command along with some default values. This definition resides in an index file in the src directory. You can change the location of this file as long as you provide the correct path to it in your package.json file.

WARNING Once you have published your app, you must not change the id, name, or code properties for any of your definitions.

Implement

Once you have generated the scaffolding for your application using ShipEngine Connect CLI, add your implementation for each method your application supports. Likewise, use the example service definition files to create unique definitions for each of the services your application provides. Finally, update the application definition to include all the methods and definitions you have implemented.

Test

As you're building your app, you'll want to run it periodically so you can test and debug your code. Luckily, ShipEngine Connect CLI includes commands to help with this, such as connect start and connect test. You can also write your own unit tests to exercise your code. See our testing page for more information.

Publish

Once all the generated tests pass, you will publish your application to ShipEngine Connect using the connect publish command. This command will publish to a development environment where further end-to-end testing may be performed before your application is published to production and made available within our suite of e-commerce solutions.

Sample Application References

If you would like to see more examples of various ways to implement and structure your applications, please have a look at our sample apps.