Development Workflow

A development workflow is the process you follow during development to save time and minimize errors. It includes stages like setup (scaffolding), development, testing, integration, optimization, and deployment.

Setup

The setup process of developing a site using platformOS includes three main steps:

1. Create a new Instance on the Partner Portal

The Partner Portal is an online interface where you can create, manage, and configure sites built with platformOS, and manage other users of the Partner Portal. The site created on the Partner Portal will be the site you deploy and sync your changes to during development.

• The sites created are called Instances. Instances have a URL, and they represent different environments, like staging or production.
• Users of the Partner Portal are called Partners. Partners have the permissions to create, manage, and configure Instances. Partners can also create and manage other Partners.

When you create an Instance, the platformOS engine saves the Instance, which – after authorization – becomes available for you to deploy and sync to.

What you’ll need:

• Access to the Partner Portal

2. Create codebase

In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. To create your codebase in a local environment follow the steps in the Working with the Code and Files topic.

What you’ll need:

• Node.js
• pos-cli

3. Setup pos-cli

The pos-cli is a command line interface that helps you deploy configuration files and assets to your platformOS site. It also allows you to use team collaboration tools like git in your workflow.

You can use the pos-cli to deploy or sync your codebase to the Instance as described in the Working with the Code and Files tutorial.

What you’ll need:

• pos-cli

4. Setup IDE - for platformos-check

The platformos-check is a tool that helps you follow platformOS recommendations & best practices by analyzing the Liquid inside your app.

What you’ll need:

• If you use VSCode - platformOS Liquid Extension
  • Windows - the extension will work out of the box, as all the dependencies - Ruby and platformOS Check are included via included executable file
  • Other systems - must manually install Ruby and platformOS Check
• If you use Vim, Emacs or anything else
  • manually install Ruby and platformOS Check
  • platformOS check is implemented using Language Server Protocol, follow instructions of how to use LSP servers in your editor. For example, for Vim you can use coc.vim and configure it:

      {
        "languageserver": {
          "platformos-check": {
            "command": "platformos-check-language-server",
            "filetypes": ["liquid", "graphql", "yaml", "yml"],
            "rootPatterns": [".platformos-check.yml", ".pos"],
            "settings": {
              "platformosCheck": {
                "checkOnSave": true,
                "checkEnter": true,
                "onlySingleFileChecks": true,
                "checkOnChange": true,
                "checkOnOpen": true
              }
            }
          }
        }
      }
    

Please note that platformos-check is automatically available as a CLI tool, which is capable to auto-correct some of the offenses, use in CI and configure to meet your needs, including writing your own checks. Learn more about platformOS check Configuration

5. Setup IDE - for GraphQL

To work efficiently with GraphQL in platformOS, it's recommended to use an IDE that supports GraphQL autocomplete, syntax highlighting, and other features. One popular choice is the GraphQL extension for VSCode.

What you’ll typically need:

1. platformOS Schema:
   You’ll need to download and place the platformOS schema.graphql file in your project’s root directory. This file contains all the GraphQL types, queries, and mutations available in platformOS, allowing your IDE to provide accurate autocompletion and validation.

   • Download the platformOS schema.graphql

2. GraphQL Configuration File:
   In your project, create a .graphqlrc.yml configuration file. This file tells your IDE where to find the schema and how to handle GraphQL documents.

   Here's an example configuration that works with most GraphQL extensions:

   schema: 'schema.graphql'
   extensions:
     languageService:
       cacheSchemaFileForLookup: true
   documents: ['**/*.{graphql}']
   

Development

Development Instances

Development Instances are used for developing, updating, and testing a site without risking the integrity of the live site.

You can set up different types of Instances (staging/production) through the Partner Portal.

• Local codebase: You develop your site (write code) in your codebase in your local environment.
• Staging Instance: The staging Instance can be used for testing, presenting the changes to the client for approval, QA (Quality Assurance), or UAT (User Acceptance Testing).
• Production Instance: The production Instance is the live site available to visitors.

Based on the project’s size, scope, or requirements, stages from the above workflow can be removed, or additional stages can be added. For example, a testing site before staging can be added to separate testing from QA and UAT.

Development Workflow

You develop your site (write code) in your codebase in your local environment. By syncing to your developer Instance you check your changes in real time. The pos-cli sync command enables sync mode: it keeps track of changes on your local environment, and sends files that have been changed to the server. It only sends files that have changed after sync was started. It feels like working on localhost. It is recommended to use sync only for staging environments, as pushing changes immediately to production can be dangerous.

Once you have a release candidate, you can deploy it to your staging site. You can use the staging site for testing, review, QA, or UAT.

If everything works as expected on staging, you can deploy your changes to your production site, your live site accessible to visitors.

It is recommended that all developers have their own development instance, similarly to how they have their local versions. You keep source code in Git. Only production ready code goes into the master branch and you deploy the code from master to production.

This is a diagram of our recommended development workflow:

Related topics

• pos-cli
• Directory structure
• Working with the Code and Files
• Working with the Code and Files