Creating Your First App
ShipEngine Connect CLI provides you with everything you need to get started with your integration application.
Using the CLI
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:
Run the following command:
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
Enterto accept the default name.
Use the arrow keys to select which app type you'd like to create, then press
Enter a description for your application, and press
Enter a value to be used in the author property of your
package.jsonfile. 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
Enterto accept the default.
Enter a value to be used in the version property of your
package.jsonfile. This value defaults to
Enterto accept the default value, and then increment this property in your
package.jsonfile anytime you publish your application.
Use the arrow keys to select either
TypeScriptas your language and press
All done! You now have the application structure laid out, and you are ready to provide the implementation.
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.
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,
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
WARNING Once you have published your app, you must not change the
codeproperties for any of your definitions.
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.
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,
connect start and
connect test. You can also write your own unit tests to exercise your code. See our testing page for more information.
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.