Start typing to search...
DocsTutorialsReference
Back to withkoji.com
Docs
Publishing and maintaining templates
Publishing local projects
Search

Publishing a project you developed locally

Although Koji provides a feature-rich online project editor, you might prefer to use your own suite of development tools in some cases. In the previous parts of this tutorial, you learned how to use Git to clone a Koji project to your development machine and how to install and launch a Node.js server to run your project locally. If you have followed the first two parts of this tutorial, you will now have a scaffold project running on your local computer, so you can use your favorite text editor to modify it and add new features. You will also be able to test that these new features work on your development machine.

In this tutorial, you will learn how to push the changes that you have made locally to your project’s origin repository, and how to pull the latest version of your project into the Koji editor, where you can publish it to the world.

Note
 It is recommended that you test the publishing process before you get deep into development locally. You can make a minor change, push it back to the Koji servers, and check that the change is visible in the published template on Koji.

This is the final part in a three-part tutorial.

  1. use-git.html

  2. work-locally.html

  3. Publishing the project you developed locally (this tutorial)

Prerequisites

  • Use Git to clone your project locally. See the first part of the tutorial.

  • Install Node.js and launch your project locally. See the second part of the tutorial.

Changing a custom value

For the Element Match game, a new game title would be a simple change that is obvious to test. To change the title in the Koji editor, you would click VCC Explorer > Game Settings on the left side, which opens the Game Settings editor in Visual mode. This mode shows the visual controls that will enable non-technical users to customize your template when you have finished developing it.

Because Visual mode is not available when you are developing your project locally, you must edit the JSON customization file directly.

  1. Open the .koji/customization/string.json in your text editor.

  2. Change the title and save the file.

      "strings": {
    "fontFamily": "https://fonts.googleapis.com/css?family=Lilita+One",
    "title": "CUSTOM TITLE", (1)
    "instructions1": "Swipe the Elements to move them",
    ...
  }

    1. Change the value for the title key.

  3. In your browser, go to http://0.0.0.0:8080, and make sure the splash screen shows the new title.

Moving changes from local to live

To make a local change visible on Koji server, you must complete the following process.

  1. Use Git to commit your changes locally.

  2. Use Git to push the committed changes to the remote Koji repository.

  3. Use the instance of Git in the Koji editor to pull the committed changes from the Koji repository.

  4. Update the Node modules for the frontend and backend servers.

  5. Use the Koji editor to publish the updated version of your template.

Committing changes locally

The Git version control system keeps track of every change you make the files in your project. To see which files have changed, use the command git status.

Note
 The .gitignore file at the root of your project lists the files that Git does not track for changes. You might not see the file if your operating system is configured to hide files whose names begin with a dot. In particular, this file tells Git to ignore any changes to files in the node_modules folders, which were created when you ran npm install in the frontend and backend folders.

When you are ready to test your changes on the Koji server, use Git to commit your changes locally.

  1. Open a terminal window and go to the root directory of your project (for example, MyKojiTemplate).

  2. Run the following Git commands.

    $ git add . (1)
$ git commit -m "your comments" (2)

    1. Processes all the documents that you have changed.

    2. Creates an updated version of your project.

    Note

    Be sure to replace your comments with a brief description of the changes that you have made, so that you will be able to remember what features you were working on.

    For a more complete description of the git add and git commit commands, see this tutorial.

Pushing changes to the Koji repository

After the commit process is successfully completed, you use Git to upload the committed changes to the repository on the Koji servers.

  1. Open a terminal window and go to the root directory of your project.

  2. Run the following command.

    git push origin master

  3. At the username prompt, enter your username on Koji and press Enter.

  4. At the password prompt, enter the access key that you generated in a previous tutorial and press Enter.

    Your terminal will look something like this:

    $ git push origin master (1)
Counting objects: 21, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (21/21), done.
Writing objects: 100% (21/21), 84.53 KiB | 0 bytes/s, done.
Total 21 (delta 15), reused 0 (delta 0)
Username for 'https://projects.koji-cdn.com': KojiCoder
Password for 'https://KojiCoder@projects.koji-cdn.com': (2)
To https://projects.koji-cdn.com/a70f8329-e89e-48b0-8d85-7658c1542b9f.git
  a88036c..ea6bda1  master -> master

    1. Use Git to upload your new version to the Koji repository

    2. Paste your 32-character access key.

Pulling changes into the Koji editor

If you test your template in the Koji editor now, you will not yet see the changes you pushed. The Koji editor uses its own repository, which is different from the origin repository to which you pushed your changes. To update the repository used by the Koji editor, you must pull the changes from the origin repository.

  1. Open your project in the Koji editor.

  2. Open a new terminal tab and run the following command.

    git pull origin master

    Your terminal will look something like this:

    root@ip-172-31-12-226:/usr/src/app# git pull origin master
remote: Counting objects: 21, done.
remote: Compressing objects: 100% (21/21), done.
remote: Total 21 (delta 15), reused 0 (delta 0)
Unpacking objects: 100% (21/21), done.
From https://projects.koji-cdn.com/a70f8329-e89e-48b0-8d85-7658c1542b9f
* branch            master     -> FETCH_HEAD
  a88036c..ea6bda1  master     -> origin/master
Updating a88036c..ea6bda1
Fast-forward
backend/package-lock.json        | 41 ++++++++++++++++++++++++++++++-----------
frontend/package-lock.json       | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------
.koji/customization/strings.json |  2 +-
3 files changed, 92 insertions(+), 33 deletions(-)

    The code in the Koji editor should now be identical to the code in your local repository.

  3. In the top right of the Preview pane, click Refresh to make sure you are seeing the latest version.

    You should now see the custom title, which corresponds to the local change you made in .koji/customization/strings.json.

Updating the Node modules

If you installed new or updated Node modules locally, you must also install these versions on the Koji server. For example, if you ran npm audit fix to update all the Node modules to their most recent stable release, the dependencies for the backend and the frontend servers might have changed. The package.json and package-lock.json files in the backend and the frontend directories should contain the information needed to update your Node modules to the correct versions.

  1. In the Terminal pane, click the frontend tab.

  2. Press Ctrl+C to cancel the running process.

  3. Run the following command.

    npm install

    NPM installs the files listed in the package-lock.json file for the frontend service.

  4. When the installations are finished, run the following command.

    npm start

    Your terminal will look something like this:

    ^C
root@ip-172-31-15-216:/usr/src/app/frontend# npm install
npm WARN meta-project@1.0.0 No repository field.
npm WARN meta-project@1.0.0 No license field.
... (more warnings and comments not shown) ...

audited 12334 packages in 5.192s
found 1 low severity vulnerability
  run `npm audit fix` to fix them, or `npm audit` for details
root@ip-172-31-15-216:/usr/src/app/frontend# npm start
... (more output not shown) ...

ℹ ｢wds｣: Compiled successfully

  5. In the Terminal pane, click the backend tab.

  6. Press Ctrl+C to cancel the running process.

  7. Run the following command.

    npm install

    NPM installs the files listed in the package-lock.json file for the backend service.

  8. When the installations are finished, run the following command.

    npm run start-dev

    Your terminal will look something like this:

    ^C
root@ip-172-31-15-216:/usr/src/app/backend# npm install
npm WARN koji-project-backend@1.0.0 No description
npm WARN koji-project-backend@1.0.0 No repository field.
... (more warnings and comments not shown) ...

audited 8550 packages in 2.729s
found 0 vulnerabilities

root@ip-172-31-15-216:/usr/src/app/backend# npm run start-dev
... (more output not shown) ...

[koji] backend started

Publishing a new version

To complete the first iteration of the development cycle, you must publish your template so that you can test how it works when served live on the Koji servers. Since your template is under development, you might not be ready to broadcast it to the whole web. For now, you might prefer to test the template live yourself or get feedback from a small, hand-picked group. Fortunately, Koji gives you a way to publish your project as unlisted, which means that only people with the direct URL are able to visit your published template.

  1. In the upper left of the Koji editor, click Publish Now to open the publish settings.

  2. To publish your project as unlisted, click Show advanced options, and then select the Unlisted checkbox.

    Note
    		 The next time you publish your template, the Unlisted option will be selected by default. Remember to clear this setting when your project is ready for the world to see.

  3. If needed, edit additional information about your template, such as the name and description.

  4. Click Publish New Version.

    A message appears to indicate that the publishing process has started. When publishing is completed, a link appears in the message.

    Tip
    		 When you publish your project, the Koji editor automatically creates a new Git commit with the commit message Manual deploy.

Developing customization files for your template

When you need to change the customization files for your template, the Koji editor provides several important features that are not available in your local development environment.

  • A Visual mode for editing the JSON files stored at .koji/customization/.

  • The ability to generate custom URLs for assets.

If you edit the customization files in your local development environment, you could create valid JSON that does not conform to the format required by Koji. In particular, the @@editor array needs to contain specific property-value pairs and precisely constructed objects, or the VCCs will not work and non-technical users will not be able to customize your template correctly. To ensure that your changes are valid and work as expected, it makes sense to work in the Koji editor, and to toggle back and forth between the Visual and Code modes.

Another reason to use the Koji editor is that you can upload images and audio files, or provide a direct URL to where these files can be found online, and the Koji platform will copy them to the Koji CDN servers and insert the appropriate URL into the associated JSON file for you. Working in your local development environment, there is no way for you to transfer files to the Koji servers and to obtain their URLs.

However, editing the customization files in both the Koji editor and in your local development environment can cause problems. If you were to edit the JSON file structure or upload assets in the Koji editor, you would need to manually push the changes to Koji’s origin repository and then pull them into your local development environment. If you had also made local changes since your last local commit, this might result in conflicts between the Koji editor’s repository and your local Git repository.

To get the benefits of the Koji editor while avoiding potential conflicts between repositories, the recommended solution is to use a separate Koji project for developing your customizations.

  1. Create a separate Koji project specifically for editing the JSON customization files, and nothing else.

  2. For each of the JSON files stored in the .koji/customization/ folder of this separate project, edit the @@editor array until the Visual mode works as needed.

  3. Use the Visual mode to set the default values that you want in your main project. Upload files or provide links to custom assets.

  4. When you have finished customizing the values in the Koji editor, switch to Code mode and copy the JSON content.

  5. In the local development environment for your main project, paste this tried-and-tested VCC code into the appropriate JSON file.

  6. Commit your changes locally, push to the Koji origin repository, and pull the changes into the Koji editor of your main project.

    Important
    		 By following this process, you can be sure that your modified code always flows only in one direction: from your local development environment to the online Koji environment.
Tip
 The separate Koji project that you use for editing and testing the VCC JSON files can be reduced to its bare bones, if you want. You can delete all the frontend and backend code, and retain just the .koji directory and its contents. You can even use the same project to develop the VCC JSON files for multiple projects.

Wrapping up

This tutorial has taken you on a round trip from the Koji editor to your local development environment and back again. You have seen changes that you made locally served live from the Koji servers. As you develop your project, you will cycle through many such loops, adding and refining features and testing that everything works just as well from the Koji servers as from the comfort of your own development machine.

In particular, you have seen how to:

  • Clone a remixable Koji project onto your development machine (part 1).

  • Install a Node.js server environment and run your project locally (part 2).

  • Make and test changes locally.

  • Push your changes to the origin repository, and then pull them into the Koji editor.

  • Publish your changes to the Koji server.

  • Test that your template works the same live on a Koji server as it does locally.

  • Take advantage of the Visual mode for the JSON customization files, so that non-technical users can easily create their own versions of your template.

You’re now ready to start developing your Koji template in earnest, in the development environment where you feel most comfortable. Let your creativity shine!