Create components using command-line tools

The OSF command-line interface includes several commands that you can use to simplify the process of creating a widget and supporting components.

You can use these commands to create templates for building the following types of components:

widgets
actions
fetchers
endpoints

The commands create the files and folders that make up the structure of the components. Many of these files include comments that supply guidance about writing the code and supplying the configuration for the component. The guidance assumes you are writing a sample currency selector widget and the supporting components, but you can supply logic for any type of widget you want.

Create a widget

To create a widget, you use the create-widget command. For example:

yarn occ create-widget --name MyWidget

[cli] info: Creating Widget: MyWidget
[cli] info: Widget path: packages\apps\blank-store\src\plugins\components
[cli] info: App locals - en,de
[cli] info: Creating new widget folder packages\apps\blank-store\src\plugins\components\my-widget
[cli] info: Writing template files to packages\apps\blank-store\src\plugins\components\my-widget
[cli] info:      config\index.js
[cli] info:      config\locales\en.js
[cli] info:      config\locales\de.js
[cli] info:      index.js
[cli] info:      locales\en.js
[cli] info:      locales\de.js
[cli] info:      meta.js
[cli] info:      README.md
[cli] info:      styles.css
[cli] info:      __test__\my-widget-widget.spec.js
[cli] info:      __test__\my-widget.spec.js
[cli] info: Updating exports for files:
[cli] info:     packages\apps\blank-store\src\plugins\components\index.js
[cli] info:     packages\apps\blank-store\src\plugins\components\meta.js

This command creates a widget named MyWidget in the default application in the workspace. For example, if the default application is named my-app, the widget files are created in packages/apps/blank-store/src/plugins/components/my-widget.

To create a widget in an application other than the default application, you can specify the application name in the command. For example:

yarn occ create-widget my-other-app --name AnotherWidget

Create an action

To create an action, you use the create-action command. For example:

yarn occ create-action --name myAction

[cli] info: Creating action: myAction
[cli] info:      Action exported as _myAction
[cli] info:      Action's Path: src/plugins/actions
[cli] info: Creating new action folder packages\apps\blank-store\src\plugins\actions\my-action
[cli] info: Writing template files to packages\apps\blank-store\src\plugins\actions\my-action
[cli] info:      index.js
[cli] info:      meta.js
[cli] info:      schema\input.json
[cli] info:      __test__\index.spec.js
[cli] info: Updating exports for files:
[cli] info:     packages\apps\blank-store\src\plugins\actions\index.js
[cli] info:     packages\apps\blank-store\src\plugins\actions\meta.js

When you create an action, you can also create a reducer that the action invokes:

yarn occ create-action --name myAction --reducer

The reducer is created in the action's index.js file.

You can also specify an endpoint that the action invokes:

yarn occ create-action --name myAction --endpoint myEndPoint

Note that this command doesn't create the endpoint, it just specifies the name of the endpoint required by the action. You can either specify an endpoint that has already been created, or write one afterward with the name you specified. (If you use --endpoint but omit the endpoint name, the name defaults to the name of the action.)

Create a fetcher

To create a fetcher, you use the create-fetcher command. For example, the following command create a fetcher for the HelloWorld widget:

yarn occ create-fetcher --name myFetcher --endpoint getOrder --selector mySelector --forComponent HelloWorld

Note that the specified widget must already exist. The specified endpoint and selector can already exist, or you can write ones afterward with the specified names.

You can create a global fetcher by using the --global flag rather than the --forComponent flag. For example:

yarn occ create-fetcher --name myFetcher --endpoint getSite --selector mySelector --global

Create an endpoint

To create an endpoint, you use the create-endpoint command. The version of the command that you use depends on whether your organization maintains a Swagger-based document containing a JSON representation of the REST API endpoints that can be called from widget code.

To create an endpoint from a Swagger document, you use the --swaggerUrl flag. For example:

yarn occ create-endpoint --directoryName swagger-endpoints --swaggerUrl http://www.example.com/catalogApi --endpoints getOrder,putOrder

The --directoryName flag specifies the subdirectory (relative to the application's \src\plugins\endpoints directory) to create the endpoint in. The command creates the specified directory; it cannot already exist.

The --endpoints flag is used to specify a comma-separated list of the IDs of the REST endpoints in the JSON document. There are two ways to specify these IDs:

If the JSON document includes an operationId value for each endpoint, use these values to specify the endpoints. The example above illustrates using these values.
If the JSON document does not include operationId values, use the zero-based index of the ordering of the REST endpoints in the document. For example, to specify the first and fifth endpoints in the file, you would use --endpoints 0,4.

Note that you can display a list of all the endpoints in a Swagger document by using the list-endpoints command. For example:

yarn occ list-endpoints --swaggerUrl http://www.example.com/catalogApi

To create an endpoint without a Swagger document, you use the --url flag to specify the URL of an individual REST endpoint, and the --verb flag to specify the HTTP verb. For example:

yarn occ create-endpoint --directoryName other-endpoints --url http://www.example.com/orders --verb GET