Start typing to search...
Developer DocsAPI Reference
Back to withkoji.com

Set up your local environment

In the first section of this tutorial, you learned how to use Git to clone a Koji app to your development machine, so that you can work on it locally. In this section, you will install a Node.js web server environment on your development machine and launch both a frontend and a backend server so that you can work with all aspects of your app within your local area network.

Learning objectives

By the end of the section, you should feel comfortable:

  • Installing the Node modules that are needed to run a server on your local machine.

  • Setting the environment variables used by the server.

  • Specifying the URL the frontend will use when connecting to the backend server.

  • Launching the app locally and checking that the game and the leaderboard are working correctly.

  • Overriding the Koji debugger settings so you can test additional functionality in your locally running app.

Prerequisites

  • Use Git to clone the Falling Objects game locally. See the first part of the tutorial.

  • Install Node.js and its associated Node Package Manager (NPM). In this tutorial, you will set up a Node.js server on your development computer. Koji uses Node.js and add-on packages to deliver your web application to your users' browsers.

Installing the dependencies

In the previous tutorial, you used Git to clone all the project-specific files to your local drive. However, the files that actually run the local server have not yet been installed. Fortunately, four of the cloned files contain all the information about the servers and other dependencies that you will need to set up the server environment and launch the app locally. These are the package.json and package-lock.json files in the frontend and backend directories.

Before you can test the app on your development machine, you must install two sets of Node modules, one set to run the frontend and another set to run the backend.

  1. Open a terminal window, and go to the backend directory.

  2. Run the following command.

    npm install

    NPM reads the contents of the package-lock.json file and installs the listed files in a node_modules directory within the backend directory. You’ll have to wait for a few minutes while the terminal window shows you what’s happening.

    ~/Repos/Koji/MyKojiApp$ cd backend
~/Repos/Koji/MyKojiApp/backend$ npm install

> core-js@2.6.9 postinstall /home/kojicoder/Repos/Koji/MyKojiApp/backend/node_modules/core-js
> node scripts/postinstall || echo "ignore"

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) ...

added 477 packages from 234 contributors and audited 8550 packages in 6.678s
found 0 vulnerabilities

  3. Go to the frontend directory and run the following command.

    npm install

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

    ~/Repos/Koji/MyKojiApp$ cd ../frontend/
~/Repos/Koji/MyKojiApp/frontend$ npm install

> koji-tools@0.5.3 postinstall /home/kojicoder/Repos/Koji/MyKojiApp/frontend/node_modules/koji-tools
> node ./cmd.js postinstall

new config

> preact@8.5.1 postinstall /home/kojicoder/Repos/Koji/MyKojiApp/frontend/node_modules/preact

> webpack-cli@3.3.1 postinstall /home/blackslate/Repos/Koji/MyKojiApp/frontend/node_modules/webpack-cli
> node ./bin/opencollective.js

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) ...

added 996 packages from 358 contributors and audited 12188 packages in 14.023s
found 345 vulnerabilities (1 low, 344 high)
  run `npm audit fix` to fix them, or `npm audit` for details

  4. If you want to update all the Node modules to their most recent stable release, you can run the following command.

    npm audit fix

    Your terminal will look something like this:

    ~/Repos/Koji/MyKojiApp/frontend$ npm audit fix
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) ...

removed 2 packages and updated 4 packages in 7.468s
fixed 344 of 345 vulnerabilities in 12188 scanned packages
    Note
    		 This process alters the package-lock.json file, so that it can request the identical file versions if you run npm install on a different computer.

  5. Check for outdated dependencies in the forked app, and update them if necessary.

    Tip
    		 Keep the withkoji-koji-core.html package updated to ensure your app has access to the latest platform features and bug fixes.

    1. Run npm outdated to discover dependencies that you might need to update.

      Your terminal will look something like this.

      $ npm outdated
Package                                Current  Wanted  Latest  Location                                            Depended by
@withkoji/core                          0.0.17  0.0.17   1.7.3  node_modules/@withkoji/core                         frontend
... (some output not shown) ...

    2. If the @withkoji/core package is outdated, check the package release notes for breaking changes that could affect your app, and update your code, if needed.

    3. When you are ready to upgrade, run the following command.

      npm install @withkoji/core@latest

    4. Repeat the process for other packages, as necessary.

Launching your project locally

The Falling Objects game features both a frontend – so that you can play the game in your browser – and a backend – to access a database where the leaderboard scores are stored.

Launching projects without a backend

If you chose to develop an app that does not require a backend, such as a game without a leaderboard, launching your project locally is very simple.

  1. Go to the frontend directory and run the following command.

    npm start

    Your terminal will look something like this:

    $ cd frontend/
$ npm install
$ npm start

... (some output not shown) ...
ℹ ｢wds｣: Project is running at http://0.0.0.0:8080/
ℹ ｢wds｣: webpack output is served from /
... (more output not shown) ...

ℹ ｢wds｣: Compiled successfully

  2. To see and test your project, go to http://0.0.0.0:8080 in your browser.

    Alternatively, http://localhost:8080/ and http://127.0.0.1:8080/ might also work.

Launching projects with a backend

If you want to run a project with a backend, such as a leaderboard, the procedure for launching your app is more complex. You must launch both the frontend and the backend servers on your local machine. You can manually launch the servers, using a separate terminal window for each, or you can set up a launch configuration file, if you’re working in VS Code.

Launching the frontend from the terminal

By default, the frontend is configured to run at http://0.0.0.0:8080 and the backend is configured to run on port 3333. When you launch the frontend, you must specify the URL for connecting to the backend. On Mac OS and other Unix-based operating systems, you can use the export command to specify this URL.

  1. Open a terminal window, and go to the frontend directory.

  2. Run the following command, which sets the KOJI_SERVICE_URL_backend environment variable and then launches the frontend with npm start.

    Linux
    Windows
    Linux
    export KOJI_SERVICE_URL_backend=http://0.0.0.0:3333 && npm start
    Windows
    set KOJI_SERVICE_URL_backend=http://localhost:3333 && npm start

    Your terminal will look something like this:

    $ cd ..frontend/
$ export KOJI_SERVICE_URL_backend=http://0.0.0.0:3333 && npm start

... (some output not shown) ...
ℹ ｢wds｣: Project is running at http://0.0.0.0:8080/
ℹ ｢wds｣: webpack output is served from /
... (some output not shown) ...

ℹ ｢wds｣: Compiled successfully

Launching the backend from the terminal

The backend needs the values of the KOJI_PROJECT_ID and KOJI_PROJECT_TOKEN environment variables to access the leaderboard database. You saved the environment variables that Koji uses to deploy your project before you cloned it. If you need to find the environment variables again, follow the instructions in Obtaining Koji environment variables.

  1. On your local machine, create a file named .env in the frontend of your project, and paste the two lines for the environment variables.

    Your file will look something like this (with your unique values):

    KOJI_PROJECT_ID=c00484db-827a-45bb-8541-f2c09c2f192e
KOJI_PROJECT_TOKEN=a6676f53-44fe-4109-819a-69df620ad7ed
    Important
    		 Falling Objects is written using the Create React App tool. Code written with this tool expects environment variables to be prefixed with REACT_APP_. For this reason, you need to modify the above lines as shown in the next step. If you fork an app that was not written using Create React App, you can skip this step.

  2. Since Falling Objects is a Create React app, you need to modify the two lines that set the environment variables as follows:

    REACT_APP_PROJECT_ID=c00484db-827a-45bb-8541-f2c09c2f192e
REACT_APP_PROJECT_TOKEN=a6676f53-44fe-4109-819a-69df620ad7ed

  3. Open a new terminal window, and go to the backend directory of your project.

  4. Run the following command to launch the backend.

    npm run start-dev

    Your terminal will look something like this:

    $ cd ../backend/
$ npm run start-dev

> koji-project-backend@1.0.0 start-dev /home/kojicoder/Repos/Koji/MyKojiApp/backend
> NODE_ENV=development babel-watch -L --watch ../.koji/ src/server.js

[koji] backend started

    Before npm starts the backend Node.js server, it reads the values in the .env file into the environment variables, so the backend server knows how to contact the Koji database.

    Note
    		 The Koji database is not running on your local machine, so you will still need an active Internet connection to get the leaderboard to work. However, you will not need to make changes to the Koji database system, so you can focus on developing your app.

  5. If npm fails to read the values from the .env file, you can set the environment variables manually in the terminal before starting the server, using the KOJI_PROJECT_ID and KOJI_PROJECT_TOKEN values you copied earlier.

    Linux
    Windows
    Linux
    export REACT_APP_PROJECT_ID=c00484db-827a-45bb-8541-f2c09c2f192e
export REACT_APP_PROJECT_TOKEN=a6676f53-44fe-4109-819a-69df620ad7ed
    Windows
    set REACT_APP_PROJECT_ID=c00484db-827a-45bb-8541-f2c09c2f192e
set REACT_APP_PROJECT_TOKEN=a6676f53-44fe-4109-819a-69df620ad7ed

    Tip
    		 Another alternative is to use the dotenv package to read the values from the .env file.

Launching servers from Visual Studio Code

Koji automatically generates the launch.json configuration file used by Visual Studio Code. This file contains the environment variable settings, the URL for connecting to the backend, and the deployment details needed to launch your project. With this configuration file, you can launch both the frontend and the backend servers from Visual Studio Code, instead of from the terminal.

Learn more: Launch Configurations in the Visual Studio Code documentation

Testing your local deployment

After your project is running locally, you can use your browser to verify the basic functionality. Then, you can point the Koji debugger to your localhost so that you can test all app functionality.

  1. In the terminal windows, check that the frontend reported Compiled successfully and the backend reported Server is listening on port 3333.

  2. If you see errors, make sure that no other applications are running on ports 8080 and 3333.

  3. Test the app in your browser.

    1. Visit http://0.0.0.0:8080.

      You should see the Falling Objects game running.

    2. Click Top Players to check that the leaderboard is working.

      If you haven’t played the game yet, there will be no scores to show, but you will see the Top Players title and a Close link that returns you to the Welcome screen.

    3. Click the start game icon and play the game.

    4. When the game is over, submit your user name.

      The leaderboard should now show your name and your score.

  4. Test the app in the Koji debugger.

    1. Return to the browser tab for Project Details, and click Open in Debugger.

    2. In the Koji debugger, click Open Debugger Settings.

    3. Enter the full URL of your locally running app (http://0.0.0.0:8080), and click Update.

    4. On the Remix tab, change some of the custom settings and monitor the events.

    5. Click Preview to preview your custom settings in the app, and click Refresh to reset it to the default settings.

Tip

When working locally, testing in the Koji debugger offers several advantages over testing in your browser.

  • You can test your app in different contexts, such as remix.

  • The window size is constrained like it will be on the platform.

  • You can test functionality that requires communication with the Koji platform, such as in-app purchases. To test purchases, you must register the product by publishing your app once, which you will do in the next section of the tutorial.

For more information, visit Using the Koji debugger.

Wrapping up

In this part of the tutorial, you learned how to install a Node.js web server environment, launch a frontend and a backend server, and override Koji debugger settings, so that you can test and debug your app while working locally.

You are now ready to start editing the app on your development machine and turning this project into your own app. With what you have learned so far, you will be able to test all aspects of your app locally.

When you’re ready to deploy your app for end users, you must publish it so they can access it from the Koji server. To publish your app, you must update the repository that the Koji server uses to deliver your app. For more information, see publish-locally-developed.html.