Getting projects started can be challenging. Sometimes half our battle is just setting up the project to run. Hackathon and game jam projects take a lot of time, so preparing and getting our apps up and running can make a huge difference in our progress and polish.
Inspired by Sahat’s Hackathon Starter project, we built a project for Node.js. We designed the project for ideas that can benefit from having a queryable database during hackathons. Our hackathon starter kit gets you started by providing both a React frontend app and a backend that can easily store and access your data on a CockroachDB. With this setup, you can jump right into your project’s ideation and creation.
This article walks through our DBHackathon Starter Kit, each component of its code, and how to build and run it.
A Hackathon Kit for Databases
Data has become a critical piece that drives apps. For example, a location app needs a searchable list of countries and locations, and apps that allow account creation need to store and look up users. However, configuring and iterating on a data-driven application can still be a challenge to get started and often confusing to dig through the documentation and examples.
This starter kit’s goal is to help minimize that ramp-up time for hackathon developers working with JavaScript. The kit makes it easy to import and work with the project’s data through CockroachDB.
CockroachDB and CockroachCloud
CockroachDB is a free, highly scalable SQL database solution that we can deploy on our servers. CockroachCloud is the cloud version that Cockroach Labs deploys and manages, so we can just connect to and use it.
After importing data into the CockroachDB, we can use existing SQL tools to sift through the data and run queries on it directly.
The Cockroach Labs team currently provides a free beta CockroachCloud tier to which the starter kit connects. You can use the tier for proofs-of-concept and smaller programs. The account is free forever, so sign up on the CockroachCloud website to use CockroachCloud with the starter kit.
What the Starter Kit Does Out of the Box
The starter kit’s code does much of the initial work for us. The code uses Sequelize.js to connect to CockroachDB and provides functions to import, add, update, and remove data with examples in a test() function and a /test endpoint. We organized the kit so that it’s easy to define a custom DB model and iterate on it.
We can quickly load data from CSV or JSON objects into the CockroachDB then query and use the data. We also created a server and client-side React app that we can turn into an easily demonstrable app. We can build it for release by running npm build in the app folder.
Primary Technologies and Project Structure
The main tech stack this kit relies on includes:
- Node.js, the project’s main server
- Express, the backend APIs
- React.js, the frontend app
- CockroachDB and CockroachCloud, for storing the data
- Sequelize, for object-relational mapping (ORM) to connect to the CockroachDB
We organized the project to keep the DB model and server code at the top level and the frontend React app inside the app folder.
Let’s go through the contents of each folder and index.js:
- app: Contains the entire frontend application. You can edit src/App.js to update the starter client app, which provides an interface to control the server and add data to the set.
- data: Sample CSV datasets that the example DB models use and can be easily imported into the database. (Source: ISO Language Codes Dataset, Country List)
- db: Code for defining your DB model. The DB_*.js files are model examples that demonstrate how to import data into CockroachDB easily. You can use these examples as reference templates for new projects.
- utils: Some useful basic utility functions.
- index.js: The main server code with the DB model instance and routes. It needs editing.
Getting Started
To use this starter kit, first, clone or download the repository.
Next, open the project directory inside a prompt or terminal and run npm install to set up its dependencies.
Then, set up the CockroachDB and CockroachCloud connection by creating a .env file at the project root. Add environment variables to the file based on the connection string and password.
If you haven’t set up CockroachDB yet, you can sign up for CockroachCloud for free. Or, you can download and install CockroachDB Core if you wish to run the project from a local database.
For CockroachCloud, download the cc-ca.crt file to your project folder. When you’ve completed this part, you should have a connection URL that looks like this:
postgres://instafluff:z6NShLj3ux@free-tier4.aws-us-west-2.cockroachlabs.cloud:26257
/defaultdb?sslmode=require&options=--cluster=instafluff-288
Example .env File
COCKROACHDB_USER=instafluff
COCKROACHDB_PASS=z6NShLj3ux
COCKROACHDB_HOST=free-tier4.aws-us-west-2.cockroachlabs.cloud
COCKROACHDB_PORT=26257
COCKROACHDB_DATABASE=instafluff-288.defaultdb
COCKROACHDB_CERTIFICATE=cc-ca.crt
Finally, we run node index.js to run the server.
In another prompt or terminal window in the project directory, run cd app, and npm start to start the React app. Then you see the client-side app, and you can interact with the buttons to run the test() function and search languages by language code.
Language Code Search
Let’s take a quick detour to look at the Language Code Search example to better understand how the starter kit works.
When we open db/DB_Languages.js, we see the code for this model’s column definitions and functions. The model initializes by loading from a CSV file containing language codes and their corresponding names in English. Then, the test function contains examples of how to remove, update, and query the data.
Because the data persists inside the CockroachDB through restarts of the server, we can update any entry and it will stay updated in the database. We can also search for languages using the two-letter language code using the React app by typing the code into the Search text box and clicking the Run button.
You can try looking up different languages by code such as fr, es, or de.
What’s Next?
The hackathon starter kit helps build Node.js apps based on an example database app. The kit provides the basics needed to understand better how to create a data-driven app quickly.
Now that you are ready with this starter kit, how about building something fun?
We included an example dataset for a list of countries and their two-letter codes in DB_Countries.js as another reference for creating a DB model.
You can try some of these other ideas:
- World Cities lookup for latitude/longitude on a map
- Historical weather data lookup and analysis
- Movies titles and reviews
- Animal information lookup app
If you make improvements to the GitHub repository, please consider submitting a pull request so other developers benefit from your changes.
Happy learning!
To start on your next project, sign up for Cockroach Cloud and try CockroachDB for yourself.
If you’re interested in developing expert technical content that performs, let’s have a conversation today.
