🎭 Jokester

• ✨ Features
• 🔴 Live Demo
• 🛠️ Tech Stack
• 📁 Project Structure
• ⚙️ How It Works
• 🚀 Getting Started
• 🌐 API Reference
• 🎨 Design Highlights
• 🔒 Error Handling
• 📦 Deployment
• 📚 Learning Objectives
• 🙌 Credits

🌐 https://jokester-omega.vercel.app/

Open the link, pick your filters, hit the button — and get a joke instantly.

Frontend        → HTML5 · CSS3 · Vanilla JavaScript · EJS Templating
Backend         → Node.js · Express.js
HTTP Client     → Axios
API             → JokeAPI v2 (free, no auth, CORS-enabled)
Fonts           → Google Fonts (Fraunces + Nunito)
Hosting         → Vercel

• Express.js — minimal, fast server framework ideal for routing and middleware
• Axios — cleaner API than fetch for server-side HTTP requests, with built-in error handling
• EJS — simple templating that lets the server inject dynamic data directly into HTML
• JokeAPI — free, no API key needed, CORS-enabled, and returns structured JSON with rich filtering options

jokester/
│
├── index.js                  ← Express server (routes, Axios calls, error handling)
│
├── views/
│   └── index.ejs             ← Main EJS template (all dynamic rendering)
│
├── public/
│   ├── css/
│   │   └── style.css         ← All styles (neo-brutalist design system)
│   └── js/
│       └── app.js            ← Client-side JS (punchline reveal, pill sync)
│
├── package.json              ← Dependencies and npm scripts
├── vercel.json               ← Vercel deployment configuration
└── README.md                 ← You are here

User fills form  →  POST /joke  →  Express builds API URL  →  Axios calls JokeAPI
                                                                      ↓
Browser renders  ←  EJS renders  ←  Express passes joke data  ←  Response received

1. User visits GET / — the home page renders with an empty state and the filter form.
2. User configures their joke preferences (category, format, blacklist flags) and submits.
3. Express receives the POST /joke request and reads req.body.
4. The server constructs a dynamic JokeAPI URL:

   https://v2.jokeapi.dev/joke/{category}?blacklistFlags={flags}&type={type}
   

5. Axios sends the GET request to JokeAPI and awaits the response.
6. The data is passed into the EJS template, which renders the joke differently based on type (single vs twopart).
7. For two-part jokes, a JavaScript button hides the punchline until the user taps to reveal it.

Make sure you have the following installed:

• Node.js v18 or higher
• npm (comes with Node.js)

git clone https://github.com/razazaheer12/Jokester.git
cd Jokester

npm install

# With auto-reload (recommended)
npx nodemon index.js

# Or run once without nodemon
node index.js

http://localhost:3000

That's it — no .env file, no API keys, no additional setup required.

This project uses JokeAPI v2 — completely free, no authentication required.

https://v2.jokeapi.dev/joke/{category}

GET https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,explicit&type=twopart

{
  "error": false,
  "category": "Programming",
  "type": "twopart",
  "setup": "Why did the programmer quit his job?",
  "delivery": "Because he didn't get arrays.",
  "flags": {
    "nsfw": false,
    "religious": false,
    "political": false,
    "racist": false,
    "sexist": false,
    "explicit": false
  },
  "id": 210,
  "safe": true,
  "lang": "en"
}

Any · Programming · Misc · Dark · Pun · Spooky · Christmas

nsfw · religious · political · racist · sexist · explicit

The UI uses a neo-brutalist design language with a bright, playful twist:

• Typography — Fraunces (serif, italic) for jokes; Nunito (rounded sans-serif) for UI
• Color palette — Sunshine yellow #FFE14D, coral #FF6B6B, mint #4ECDC4, and navy #1A1A2E
• Cards — thick 2.5px borders + hard 6px offset box shadows for that chunky, tactile feel
• Animated blobs — blurred color blobs float in the background using CSS @keyframes
• Interactive pills — category and filter buttons toggle with smooth hover + active states
• Reveal animation — the joke card pops in with a spring cubic-bezier animation on each new result
• Mobile-first — layout adapts gracefully from 320px screens upward

Errors are handled at two levels:

try {
  const response = await axios.get(url);
  const data = response.data;

  if (data.error) {
    // JokeAPI returned no results for these filters
    return res.render("index", { joke: null, error: "No jokes found...", query: req.body });
  }

  res.render("index", { joke: data, error: null, query: req.body });

} catch (err) {
  // Network failure or API down
  console.error("JokeAPI error:", err.message);
  res.render("index", { joke: null, error: "Couldn't reach the Joke API right now.", query: req.body });
}

<% if (error) { %>
  <div class="alert alert-error">
    <span class="alert-icon">😅</span>
    <p><%= error %></p>
  </div>
<% } %>

The form also preserves user selections after an error, so they don't have to re-configure their filters.

This project is deployed on Vercel with a custom vercel.json configuration to support the Express server.

{
  "version": 2,
  "builds": [{ "src": "index.js", "use": "@vercel/node" }],
  "routes": [{ "src": "/(.*)", "dest": "index.js" }]
}

# Install Vercel CLI
npm install -g vercel

# Deploy from your project root
vercel

# Follow the prompts — your site will be live in seconds

This project was built to demonstrate: