Hackathon Starter

Live Demo: Link

Jump to What's new?

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!”
— Adrian Le Bas

“Awesome. Simply awesome.”
— Steven Rueter

“I'm using it for a year now and many projects, it's an awesome boilerplate and the project is well maintained!”
— 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!”
— Interview candidate for one of the companies I used to work with.

Modern Theme

Flatly Bootstrap Theme

API Examples

Table of Contents

• 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

•  Mac OS X: Xcode (or OS X 10.9+: xcode-select --install)

•  Windows: Visual Studio Code + Windows Subsystem for Linux - Ubuntu OR Visual Studio

•  Ubuntu /  Linux Mint: sudo apt-get install build-essential

•  Fedora: sudo dnf groupinstall "Development Tools"

•  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:

1. 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.
2. 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:

• Deployment
• prod-checklist.md

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.

• Visit Google reCAPTCHA Admin Console
• 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 Google Cloud Console
• 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 Snap Kit Developer Portal
• 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 Facebook Developers
• 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