Studio Package Blueprint

This MDK blueprint will create a working Studio Package.

Usage

1. Get the MDK: yarn global add @movable/cli
2. Create a new package: movable new my-package -b @movable/studio-framework-package-blueprint

How can I use this?

The blueprint will create a functioning package that you can learn from and modify for your own use-case. It contains:

• 2 cold state examples (multiple-canvases has 2 canvases & default has 1 canvas)
• Properties examples
• A Tool example
• A utils folder
• Starter tests
• A package manifest
• A package.json
• A rollup build file

Coldstates

• This JSON object contains the tag structure a user will see when they load an App that contains your package, provided that you've specified that the App should use your package coldstate. This is defined in the App's manifest.yml file and will look something like:

  cold_state:
    packageName: '@movable-internal/my-amazing-package'
    name: 'default'

  or:

  cold_state:
    packageName: '@movable-internal/my-amazing-package'
    name: 'multiple-canvases'

In general, the default coldstate should be the coldstate most commonly used. There is no limit to the amount of coldstates your package can have.

Properties

• Properties represent data.
• In other words, you will write code, that takes inputs that results in a value once your App is rendered.
• The inputs that you'll use can come from an API, a user in Studio, a CSV etc.
• The resulting value could be a string, a URL for an image etc...
• The resulting value will be accessed by the property path that you define. For example: fakeData.formattedCaption.
• The inputs required by users in Studio will have to be defined in package-manifest.yml.

Tools

• Tools represent a UI element. Just like properties, tools will probably need to access data from the User in Studio. Tools will have to be defined in package-manfest.yml in order to be visible in Studio. The return value of a tool is written with JSX.

Utils

• Depending on the logic of your package, you may find it useful to extract helper files into their own folder. This is just a suggestion, not a requirment.

Package Manifest

• The package-manifest.yml is one of the most important files in your package and probably the one that is the easiest to break, get wrong, update with typos etc... You will probably have to try, try again, again, then again.
• This file is written in YML. YML is notoriously picky. If your indentation is wrong, your YML is wrong. It's wise to find a YML validation tool online to pre-validate your YML.
• This is the file where you specify what data your package needs from a user. In other words, this YML will communicate to Studio the fields that should be displayed to the user and and how the user's selections get used.
• For example, the Diamond tool in this package needs a color for its border, and a name for its greeting. Look at the package-manifest.yml to see how that's done.
• In general, the package-manifest.yml defines the following:
  • What fields can the user specify?
  • What are the fields called?
  • What are the field types? (select, color etc...)
  • What are the field descriptions? ("Image from fakeData based on index number 1 - 3.")
  • Where does field data come from? Is it a field like a color picket? Is it a dynamic property that could consist of static values? query params?
  • What is a fields name. ie. HOW DOES YOUR CODE ACCESS THE FIELDS VALUES?

    - name: fakeData.image
          label: Fake Data Image
          type: image
          options_description: Image from fakeData based on index number 1 - 3.
          context_options:
            - name: postNumber
              type: select
              description: Index of your image
              options:
                - value: 0
                  label: Image 1
                - value: 1
                  label: Image 2
                - value: 2
                  label: Image 3

  • Based on the example above, your code can access the fakeData.image like:

    getProperty('fakeData.image');

Package JSON

• The package.json file created by this blueprint will contain values that you need to change.

  1. What is the name of your package? (name attribute)
  2. What libraries will your package use? (peerDependencies, dependencies and devDependencies attributes)
  3. What does your package do? (description attribute)

Rollup

• The rollup.config.js simply imports the rollup configuration that's been set up to work for all packages. It's possible (but not likely) that you would deviate from that standard setup.

Tests

• You will be tempted to skip tests and go directly to User Acceptance Testing... thinking that this will save you precious time. Debugging by UAT will an incredibly tedious and painful process. Debugging via tests is significantly easier.

User Acceptance Testing

My code is tested (and amazing) - how to I use it?

• All packages get built into an App. That build process is fascilitated 2 ways:

  1. Publish a canary version of your package. **
  2. If you want to test your coldstate, create an App that uses your package and deploy it to staging.
  3. If you simply want to test your logic in an existing App, install your package in Studio.

  **Don't publish a package until you have the tests to prove that it works.

License

Copyright 2018 Movable, Inc. All rights reserved.