Hackathon Starter

Live Demo: Link

A boilerplate for Node.js web applications.

If you have attended any hackathons in the past, then you know how much time it takes to get a project started: decide on what to build, pick a programming language, pick a web framework, pick a CSS framework. A while later, you might have an initial project up on GitHub, and only then can other team members start contributing. Or how about doing something as simple as Sign in with Facebook authentication? You can spend hours on it if you are not familiar with how OAuth 2.0 works.

When I started this project, my primary focus was on simplicity and ease of use. I also tried to make it as generic and reusable as possible to cover most use cases of hackathon web apps, without being too specific. In the worst case, you can use this as a learning guide for your projects, if for example you are only interested in Sign in with Google authentication and nothing else.

Testimonials

“Nice! That README alone is already gold!”<br> — Adrian Le Bas

“Awesome. Simply awesome.”<br> — Steven Rueter

“I'm using it for a year now and many projects, it's an awesome boilerplate and the project is well maintained!”<br> — Kevin Granger

“Small world with Sahat's project. We were using his hackathon starter for our hackathon this past weekend and got some prizes. Really handy repo!”<br> — Interview candidate for one of the companies I used to work with.

<h4 align="center">Modern Theme</h4>

<h4 align="center">Flatly Bootstrap Theme</h4>

<h4 align="center">API Examples</h4>

Features
Prerequisites
Getting Started
Obtaining API Keys
Project Structure
List of Packages
Useful Tools and Resources
Recommended Design Resources
Recommended Node.js Libraries
Recommended Client-side Libraries
Pro Tips
FAQ
How It Works
Cheatsheets
- ES6
- JavaScript Date
- Mongoose Cheatsheet
Deployment
Docker
Production
Changelog
Contributing
License

Features

Login
- Local Authentication using Email and Password
- OAuth 2.0 Authentication: Sign in with Google, Facebook, X (Twitter), LinkedIn, Twitch, Github, Snapchat
User Profile and Account Management
- Gravatar
- Profile Details
- Change Password
- Forgot Password
- Reset Password
- Verify Email
- Link multiple OAuth strategies to one account
- Delete Account
Contact Form (powered by SMTP via Sendgrid, Mailgun, AWS SES, etc.)
File upload
API Examples
- Facebook, Foursquare, Tumblr, Pinterest, Github, Steam, Quickbooks, Paypal, Stripe, Twilio (text messaging), Lob (USPS Mail), HERE Maps, Google Maps, Google Drive, Google Sheets, Alpha Vantage (stocks and finance info) with ChartJS, Last.fm, New York Times, Web Scraping,
Flash notifications
- reCaPTCHA and rate limit protection
CSRF protection
MVC Project Structure
Node.js clusters support
HTTPS Proxy support (via ngrok, Cloudflare, etc.)
Sass stylesheets (auto-compiled via middleware)
Bootstrap 5
"Go to production" checklist

Prerequisites

MongoDB (local install OR hosted)
- Local Install: MongoDB
- Hosted: No need to install, see the MongoDB Atlas section
Node.js 18+
Command Line Tools
<img src="https://upload.wikimedia.org/wikipedia/commons/1/1b/Apple_logo_grey.svg" height="17"> Mac OS X: Xcode (or OS X 10.9+: xcode-select --install)
<img src="https://upload.wikimedia.org/wikipedia/commons/8/87/Windows_logo_-_2021.svg" height="17"> Windows: Visual Studio Code + Windows Subsystem for Linux - Ubuntu OR Visual Studio
<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/9/9e/UbuntuCoF.svg/512px-UbuntuCoF.svg.png?20120210072525" height="17"> Ubuntu / <img src="https://upload.wikimedia.org/wikipedia/commons/3/3f/Linux_Mint_logo_without_wordmark.svg" height="17"> Linux Mint: sudo apt-get install build-essential
<img src="https://upload.wikimedia.org/wikipedia/commons/3/3f/Fedora_logo.svg" height="17"> Fedora: sudo dnf groupinstall "Development Tools"
<img src="https://en.opensuse.org/images/b/be/Logo-geeko_head.png" height="17"> OpenSUSE: sudo zypper install --type pattern devel_basis

Note: If you are new to Node or Express, you may find Node.js & Express From Scratch series helpful for learning the basics of Node and Express. Alternatively, here is another great tutorial for complete beginners - Getting Started With Node.js, Express, MongoDB.

Getting Started

Step 1: The easiest way to get started is to clone the repository:

# Get the latest snapshot
git clone https://github.com/sahat/hackathon-starter.git myproject

# Change directory
cd myproject

# Install NPM dependencies
npm install

# Then simply start your app
node app.js

Note: I highly recommend installing Nodemon. It watches for any changes in your node.js app and automatically restarts the server. Once installed, instead of node app.js use nodemon app.js. It will save you a lot of time in the long run, because you won't need to manually restart the server each time you make a small change in code. To install, run sudo npm install -g nodemon.

Step 2: Obtain API Keys and change configs if needed After completing step 1 and locally installing MongoDB, you should be able to access the application through a web browser and use local user accounts. However, certain functions like API integrations may not function correctly until you obtain specific keys from service providers. The keys provided in the project serve as placeholders, and you can retain them for features you are not currently utilizing. To incorporate the acquired keys into the application, you have two options:

Set environment variables in your console session: Alternatively, you can set the keys as environment variables directly through the command prompt. For instance, in bash, you can use the export command like this: export FACEBOOK_SECRET=xxxxxx. This method is considered a better practice as it reduces the risk of accidentally including your secrets in a code repository.
Replace the keys in the .env.example file: Open the .env.example file and update the placeholder keys with the newly acquired ones. This method has the risk of accidental checking-in of your secrets to code repos.

What to get and configure:

SMTP
- For user workflows for reset password and verify email
- For contact form processing
reCAPTCHA
- For contact form submission
OAuth for social logins (Sign in with / Login with)
- Depending on your application need, obtain keys from Google, Facebook, X (Twitter), LinkedIn, Twitch, GitHub, Snapchat. You don't have to obtain valid keys for any provider that you don't need. Just remove the buttons and links in the login and account pug views before your demo.
API keys for service providers in the API Examples if you are planning to use them.
MongoDB Atlas
- If you are using MongoDB Atlas instead of a local db, set the MONGODB_URI to your db URI (including your db user/password).
Email address
- Set SITE_CONTACT_EMAIL as your incoming email address for messages sent to you thru the contact form.
- Set TRANSACTION_EMAIL as the "From" address for emails sent to users thru the lost password or email verification emails to users. You may set this to the same address as SITE_CONTACT_EMAIL.
ngrok and HTTPS If you want to use some API that needs HTTPS to work (for example Pinterest or Facebook), you will need to download ngrok. Start ngrok, set your BASE_URL to the forwarding address (i.e https://3ccb-1234-abcd.ngrok-free.app ), and use the forwarding address to access your application. If you are using a proxy like ngrok, you may get a CSRF mismatch error if you try to access the app at http://localhost:8080 instead of the https://...ngrok-free.app address.

After installing or downloading the standalone ngrok client you can start ngrok to intercept the data exchanged on port 8080 with ./ngrok http 8080 in Linux or ngrok http 8080 in Windows.

Step 3: Develop your application and customize the experience

Check out How It Works

Step 4: Optional - deploy to production See:

Obtaining API Keys

You will need to obtain appropriate credentials (Client ID, Client Secret, API Key, or Username & Password) for API and service provides which you need. See Step 2 in the Getting started section for more info.

SMTP

Obtain SMTP credentials from a provider for transactional emails. Set the SMTP_USER, SMTP_PASSWORD, and SMTP_HOST environment variables accordingly. When picking the smtp host, keep in mind that the app is configured to use secure SMTP transmissions over port 465 out of the box. You have the flexibility to select any provider that suits your needs or take advantage of one of the following providers, each offering a free tier for your convenience.

Provider	Free Tier	Website
SendGrid	100 emails/day for free	https://sendgrid.com
SMTP2Go	1000 emails/month for free	https://www.smtp2go.com
Brevo	300 emails/day for free	https://www.brevo.com

Visit <a href="https://www.google.com/recaptcha/admin" target="_blank">Google reCAPTCHA Admin Console</a>
Enter your application's name as the Label
Choose reCAPTCHA v2, "I'm not a robot" Checkbox
Enter localhost as the domain. You can have other domains added in addition to localhost
Accept the terms and submit the form
Copy the Site Key and the Secret key into .env. These keys will be accessible under Settings, reCAPTCHA keys drop down if you need them again later

Visit <a href="https://cloud.google.com/console/project" target="_blank">Google Cloud Console</a>
Click on the Create Project button
Enter Project Name, then click on Create button
Then click on APIs & auth in the sidebar and select API tab
Click on Google+ API under Social APIs, then click Enable API
Click on Google Drive API under G Suite, then click Enable API
Click on Google Sheets API under G Suite, then click Enable API
Next, under APIs & auth in the sidebar click on Credentials tab
Click on Create new Client ID button
Select Web Application and click on Configure Consent Screen
Fill out the required fields then click on Save
In the Create Client ID modal dialog:
Application Type: Web Application
Authorized Javascript origins: set to your BASE_URL value (i.e. http://localhost:8080, etc)
Authorized redirect URI: set to your BASE_URL value followed by /auth/google/callback (i.e. http://localhost:8080/auth/google/callback )
Click on Create Client ID button
Copy and paste Client ID and Client secret keys into .env

Visit <a href="https://kit.snapchat.com/portal" target="_blank">Snap Kit Developer Portal</a>
Click on the + button to create an app
Enter a name for your app
Enable the scopes that you will want to use in your app
Click on the Continue button
Find the Kits section and make sure that Login Kit is enabled
Find the Redirect URLs section, click the + Add button, and enter your BASE_URL value followed by /auth/snapchat/callback (i.e. http://localhost:8080/auth/snapchat/callback )
Find the Development Environment section. Click the Generate button next to the Confidential OAuth2 Client heading within it.
Copy and paste the generated Private Key and OAuth2 Client ID keys into .env
Note: OAuth2 Client ID is SNAPCHAT_ID, Private Key is SNAPCHAT_SECRET in .env
To prepare the app for submission, fill out the rest of the required fields: Category, Description, Privacy Policy Url, and App Icon

Visit <a href="https://developers.facebook.com/" target="_blank">Facebook Developers</a>
Click My Apps, then select *Add a New App from the dropdown menu
Enter a new name for your app
Click on the Create App ID button
Find the Facebook Login Product and click on Facebook Login
Instead of going through their Quickstart, click on Settings for your app in the top left corner
Copy and paste App ID and App Secret keys into .env
Note: App ID is FACEBOOK_ID, App Secret is FACEBOOK_SECRET in .env
Enter localhost under App Domains
Choose a Category that best describes your app
Click on + Add Platform and select Website
Enter your BASE_URL value (i.e. http://localhost:8080, etc) under Site URL
Click on the Settings tab in the left nav under Facebook Login
Enter your BASE_URL value followed by /auth/facebook/callback (i.e. http://localhost:8080/auth/facebook/callback