Working with the Code and Files

One of the core concepts of platformOS is that you never work offline. You edit the files in your local filesystem with your favourite code editor, but you are constantly connected to your instance so that the platformOS engine can interpret and parse your codebase.

You write code locally, but it is executed remotely.

Proper platformOS directory structure

In order for platformOS to understand and properly interpret your code, it needs to be organized in a specific way.

The simplest method for getting the proper folder structure is to use the pos-cli init command.

Start with creating an empty folder – named in this example platformos-hello – for your project and then navigating to it from the command line:

mkdir platformos-hello
cd platformos-hello

Now, to automatically create the proper directory structure inside that folder use:

pos-cli init

The command should return a success message confirming that the directory structure was created.

This means that there are a bunch of new files and folders in your project’s root directory. We’ll explain what they are used for in the next steps of this tutorial, or - if you want to jump in to the technical details - check out the platformOS Codebase section of our documentation.

What you need to know for now is that this command creates an example HTML page with a welcome message.

Authenticate your environment

For pos-cli to know which instance is related to any particular codebase, you need to make a connection between those. Basically, you need to tell the pos-cli that your code needs to be visible under some URL.

Your instance URL is available in the Partner Portal on the Instances list.

To store your instance URL in the configuration, run a pos-cli env add command with your personal data in the parameters:

pos-cli env add <environment> --url <your instance url>

You need to give your instance a name in the <environment> parameter. Since you can connect multiple instances to a single codebase, quite often you'll want to have different environments for development and production.

Let’s assume the first created instance will be for development, thus you can name it dev. So, the example pos-cli command would look like this:

pos-cli env add dev —-url https://my-instance.staging.oregon.platform-os.com

After running this command, your default browser will open, asking you to log in to Partner Portal and authorize the app. Successful authorization will be confirmed by pos-cli:

Environment <your instance url> as dev has been added successfully.

Upload your code to an instance

When you have an instance, and the pos-cli is configured to connect with it, you can send your code to be available under the instance URL.

This process – called deployment – is a straight-forward operation where you need to use the following command in the root of your project folder:

pos-cli deploy <environment>

So, if you named the alias to your instance dev, the command would look like this:

pos-cli deploy dev

A progress indicator is shown with the deployment status and once it finishes, a message is displayed:

Deploy succeeded after X seconds

After this, enter the URL of your instance in the browser and it will display the example page that you’ve just deployed.

Testing the deployment process

To test out the whole deployment process, make some changes in the code.

If you’re following this guide, you should be able to find a file named app/views/pages/indexliquid in your codebase. Open it up in your code editor of choice and change any line. For example, locate a line with the welcome message:

Welcome to your Demo instance!

Try changing it into something more personal like:

This is my first platformOS instance!

Save the file and send the codebase to the instance by running the deploy command in the command line again:

pos-cli deploy dev

After visiting your instance URL or refreshing the previously opened page, you should see the new message there.

Upload code changes automatically when you save the file

On a daily basis, you want the instance to immediately reflect the changes you made in the code with minimum effort on your side.

We call this process syncing and it’s handled by a pos-cli command ran from the root project’s directory:

pos-cli sync <environment>

When executing this command you will learn that it does not end by itself. This is a command that you want to run and leave open while you make code changes.

What pos-cli sync is doing is basically observing your codebase, so when you save changes in a file – it automatically uploads it to your instance. It only uploads the file that changed so it’s quick and efficient.

Syncing in action

For this example, try another change in the code, but before you do it, start the sync using the following command:

pos-cli sync dev

A confirmation message saying that the synchronization has been started should appear, so find another place in the code to test how this works. Please find the Hello world title in index.liquid of the demo page and change it to something else, like Hello beautiful world.

After the change, just save the file.

In the command line you should see a confirmation message saying that the edited page was synced. Refreshing the page in the browser should confirm that everything worked and the new text content is displayed.

Syncing handles not only code changes, but also all the other assets. Images, JavaScript files, or even GraphQL queries – any change in your project directories will be automatically reflected on your instance. This also includes file renaming and deletion.

Basic overview of the directory structure

The pos-cli init command will create all of the required folders used by platformOS. The very basic directories you need to be aware of are those used to store files, web pages, and handling data.

We have a whole separate article describing each directory's function in detail if you want to jump directly into the technical aspect. The ones mentioned below are enough to start.

Assets

Every static, publicly available asset is stored in the app/assets folder. Images, JavaScript, fonts, CSS files, or any downloadable documents should go here. You can organize the files any way you want, but you might want to consider the following structure to separate various asset types:

• app/assets/images for images
• app/assets/scripts for JavaScript files
• app/assets/styles for the page CSS
• app/assets/fonts for the font files

Page

Every page that you want to create should be placed in app/views/pages. You can use pure HTML and extend it with Liquid.

Data handling

The place for schema (the structure of your database written in YAML) is app/schema. We are going to walk through creating them in the next sections of this tutorial.

GraphQL queries and mutations are used to get the data from the database or save data in it. All of those queries go to app/graphql.