This project was bootstrapped with create-react-app using the citydna template.

Just FYI...

This is a Typescript project. Typescript is a superset of Javascript that provides a better developer experience. Coming from a javascript it can seem strict and annoying at first, however, once you get going you'll never look back. Importantly, it means lots of documentation is baked right into the @citydna/ packages which you can access through most good IDEs. We recommend Visual Studio Code and it's IntelliSense.

Developing your app

If you've just cloned this repository, first run yarn to install dependencies.

Then run yarn start to run the app in local development mode.

Open http://localhost:3000 to view it in the browser:

Note: If you're creating an app in the monorepo, you might get errors when running the above. Simply add a .env file to the app root with the contents SKIP_PREFLIGHT_CHECK=true then retry the above.

Looking around

First, check out src/index.tsx. Here we're importing the components we want to preview, and injecting them into the <AppPreview /> component. If you need more than one screen for example, inject them here so you can test it during development.

Open src/citydna.Controls.tsx and you'll notice how @citydna/platform is being used to emit events. Take a look at src/citydna/citydna.Screen.tsx and you'll see the same package being used to listen for events via the useEvent hook. This is how related devices talk to each other.

For more advanced usage and leveraging the 3D model, open src/citydna.Projection.tsx and see how it's possible to add deck.gl layers and manipulate the mapbox map directly.

Finally, there's src/citydna.Settings.tsx. This component gets shown in the platform back-end when setting up a room.

A local event bus is used during testing so you don't have to worry about polluting the platform with messages. In production, web sockets via pusher are used to provide near instant communication between connected devices.

Write tests for your app

Your app will most likely be public facing. Because of this, it's essential that you write automated tests to ensure any changes or updates don't break previously build features. We've started for you in src/__tests__/integration.tsx. @testing-library/react, @deck.gl/test-utils and mapbox-gl-js-mock are included by default.

Further reading:

• Testing Javascript with Kent C. Dodds
• create-react-app.dev - Running Tests
• @testing-library Guiding principles
• Testing deck.gl Layers and Applications
• mapbox-gl-js-mock issue#27 "Instructions on how to use"

Your tests will be automatically be run everytime you publish to npm.

Prep your app for the platform

Once you're happy with your app, you can build it and publish it to npm. Open package.json and ensure your name entry begins with citydna-app-, i.e. citydna-app-wayfinding. Add an entry files:

{
  name: "citydna-app-wayfinding",
  files: ["dist"]
  ...
}

Running yarn build:app will test your app and package the Control, Screen, Projection components, along with any dependencies into single files in the dist folder. The platform uses these at runtime and injects all react context, as well as several packages, to ensure the app runs as natively as possible.

Sign up for an yarn account if you don't already have one, then run yarn publish. This will test, build, version your app and push it up to npm. Your package will now be available at https://npm.org/packages/citydna-app-wayfinding.

To test this in a live sandboxed mode on pusher, visit https://citydna.melbourne.vic.gov.au/sandbox/wayfinding

Submit your app

When you're happy your app works as expected, fill out this form to submit your app to the platform and we can get it running live in no time.