Unicorn Zoo Web Application

This Next.js web application, named Unicorn Zoo, was developed by me, Owan Hunte, as part of my Code Fellows Instructor Technical Qualifying Interview.

Demo

https://unicorn-zoo.vercel.app (you'll need to login with a Google account)

The TL;DR

The web app has been built using the following stack (highlighting what I consider worthy of mention here):

• React and of course the Next.js framework
• TypeScript
• pwa-auth web component
• Recoil lib from Facebook
• Tailwind CSS
• React-toastify lib for an easy-to-drop-in React Toast component
• Pusher to easily implement real-time updates in the app
• MongoDB

Local Development

NOTE: I prefer Yarn over NPM as my package manager of choice so this project uses Yarn.

1. Make sure you have NodeJS (>= 12.0.0) and Yarn (>= 1.17.3) installed.

2. Fork and clone this repository to your local environment.

3. Install the dependencies:

   cd path/to/app
   yarn
   

4. Create a file named .env.local in the root of the project and add the following local environment variable entries to the file:

   NEXT_PUBLIC_APP_BUILD_TARGET=local
   NEXT_PUBLIC_GOOGLE_KEY="a-google-key"
   DB_CONN_STR="your-mongodb-connection-string"
   PUSHER_APP_ID=your-pusher-app-id
   NEXT_PUBLIC_PUSHER_APP_KEY=your-pusher-app-key
   PUSHER_APP_SECRET=your-pusher-app-secret
   NEXT_PUBLIC_PUSHER_APP_CLUSTER=your-pusher-app-cluster
   

   The NEXT_PUBLIC_APP_BUILD_TARGET entry should be set to a value other than production, i.e. local or development.

   To keep the authentication side of things agile the web app uses the pwa-auth web component. Specifically it allows anyone to log in to it using their Google account. The NEXT_PUBLIC_GOOGLE_KEY entry therefore needs to be set to a valid Google key. Details on creating a Google key can be found here.

   I'm using MongoDB to persist data storage. I recommend using any MongoDB version from 4.0.x up. Set DB_CONN_STR to a valid connection string for your MongoDB instance.

   There are two collections, locations and unicorns that the application needs to have some initial data in so it can function properly. I've included 2 JSON files in the db-init/json folder, which contain a complete initial dataset you can start with.

   Real-time updates are implemented in the web app where when any user moves a unicorn, any other user that is currently logged in to the app will see that update automatically reflected on their end. I'm making use of the Pusher Node.js and client-side JS libraries to implement this feature so you will need to create your own Pusher account and create a Pusher app that the web app can use to publish/subscribe to real-time events. After doing this grab the App ID, key, secret and cluster name from the Pusher dashboard and add them to your .env.local file as shown above.

5. Start the Next.js server in development mode, specifiying the port to run the NodeJS process on. For example, if you want to run the application on port 3002 your command would be:

   PORT=3002 yarn dev
   

NOTE: You MUST explicitly pass a port number to Next.js when starting the server in development mode, as shown in the above command. Alternatively you can make the PORT environment variable available to the application any other way you deem fit.

Credits

• Favicon and site manifest logos by Gordon Johnson from Pixabay

Licence

MIT License

Copyright (c) 2020 Owan Hunte

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

• Barn image by lumix2004 from Pixabay

• West Pasture image by Pexels from Pixabay

• East Pasture image by pasja1000 from Pixabay

• On the Trails image by pasja1000 from Pixabay