DEV Community: Romain Guillemot

Tired of bloated boilerplates? I built a minimal Express + React starter

Romain Guillemot — Wed, 18 Mar 2026 08:34:01 +0000

Hey devs 👋

I’ve been working on a small starter project and I’d really love to get your feedback.

👉 It’s a minimal setup combining Express + React, designed to be simple, clean, and easy to extend:
https://github.com/rocambille/start-express-react

I also put some effort into the documentation to make onboarding smoother:
https://github.com/rocambille/start-express-react/wiki/home-en-US

💡 The idea is not to reinvent the wheel, but to offer a lightweight alternative to heavier boilerplates. Something you can actually understand and tweak without digging through tons of abstraction.

I’d love to hear your thoughts on:

The structure (too simple? not opinionated enough?)
The developer experience
Missing features or obvious improvements
Documentation clarity

If you find it useful, a ⭐ on GitHub would mean a lot and help the project get a bit more visibility 🙏

Thanks in advance for any feedback!

StartER Directory Structure: Freedom with a Framework

Romain Guillemot — Mon, 19 May 2025 06:36:33 +0000

In the world of web frameworks, there's often a trade-off between structure and flexibility. Too much structure can feel restrictive, while too much flexibility can leave developers overwhelmed by choices.

With StartER, we believe in finding the sweet spot: providing sensible defaults while giving you complete freedom to adapt as needed. Today, I'd like to walk you through one of the key aspects of StartER: its directory structure.

The Philosophy: Control is Yours

StartER's core philosophy is simple:

StartER imposes no constraints on the location of an element, as long as you adapt the code to your organization: you have control!

While many frameworks force you into rigid conventions, StartER offers a solid starting point that you're free to reorganize according to your preferences or project requirements.

Default Directory Structure

Here's what the default structure of a StartER application looks like:

.
├── .env
├── .env.sample
├── compose.yaml
├── compose.prod.yaml
├── Dockerfile
├── index.html
├── server.ts
└── src
    ├── database
    │   └── schema.sql
    ├── express
    │   ├── routes.ts
    │   └── modules
    │       └── ...
    ├── react
    │   ├── routes.tsx
    │   ├── components
    │   │   └── ...
    │   └── pages
    │       └── ...
    └── types
        └── index.d.ts

Let's break down the key components of this structure to better understand how StartER organizes your application.

The Root Directory

The root directory contains several configuration files that make your application work:

Environment Variables

StartER uses .env files to keep your sensitive information separate from your code:

.env.sample - A template that defines the current environment variables
.env - Your actual environment file with real values (created by copying .env.sample)

Required variables include:

APP_SECRET - For authentication signatures
MYSQL_ROOT_PASSWORD - For database access
MYSQL_DATABASE - Your application's database name

This separation of configuration from code is a best practice that makes deployment across different environments much easier.

Docker Configuration

StartER leverages Docker for containerization, giving you a consistent development and production environment:

Dockerfile - Defines your application container
compose.yaml - Sets up a development environment with three containers:
- server - Your application
- database - MySQL server
- adminer - Database management interface
compose.prod.yaml - Production-specific configuration

This containerized approach means you can run your application with a simple docker compose up --build, eliminating the "it works on my machine" syndrome.

Application Entry Points

index.html - References client entry point and includes Pico CSS for styling
server.ts - Connects your Express application to a Vite server

The Source Directory

The src directory is where most of your application code lives, divided into logical sections:

Database

The database directory contains your schema and client connections. StartER makes database integration straightforward while giving you the flexibility to structure your data as needed.

Express

The backend of your application lives in the express directory, with:

routes.ts - Defining your API endpoints
modules directory - For organizing business logic

React

The frontend is contained in the react directory, with:

routes.tsx - Defining your page routes
components - Reusable UI elements
pages - Full page components

Types

The types directory contains TypeScript definitions shared throughout your application, ensuring type safety across your full-stack project.

Why This Structure Works

StartER's directory structure works because it:

Separates concerns - Backend, frontend, and database code have clear boundaries
Promotes organization - Logical grouping of related files
Remains flexible - Can be adapted as your project grows
Streamlines development - Everything has a place, but you can change that place

Perfect for Education

As a framework designed with educational purposes in mind, StartER's clear structure helps newcomers understand web application architecture without getting lost in complexity. Each section has a clear purpose, making it easier to grasp the role of different components in a full-stack application.

If you're looking for a framework that gives you a solid foundation while respecting your freedom as a developer, StartER might be just what you need. It's perfect for:

Educational projects
Prototyping modern, full-stack web applications
Learning React and Express in an integrated environment
Building projects that can grow with your skills

Check out StartER on GitHub and give it a star if you find it useful!

And if you missed my previous article about how StartER solves the Express/Vite/SSR puzzle, read it here.

What aspects of web framework directory structures do you find most helpful? Open a discussion to let me know!

How StartER Solves the Express + Vite SSR Puzzle

Romain Guillemot — Mon, 05 May 2025 12:20:00 +0000

Have you ever tried to combine Express and Vite for server-side rendering in a React application?

If so, you've probably encountered the challenge of managing two separate servers and making them work together smoothly.

In this post, I'll walk you through how StartER solves this problem with a "one server" approach that not only simplifies development but also enables powerful Server-Side Rendering (SSR) capabilities.

The Problem: Two Servers, One Application

When building a modern web application with React and Express, you typically have:

A Vite development server handling hot module replacement (HMR) and React-specific features
An Express backend server managing API routes and server-side logic

Managing these as separate servers creates unnecessary complexity:

You need proxy configurations
Communication between servers becomes cumbersome
Local development requires running multiple processes
Deployment gets more complicated

StartER's Solution: One Server to Rule Them All

StartER takes a different approach by attaching a Vite development server to the Express application server, creating a single unified server. This architecture brings several benefits:

Simplified development workflow
Cleaner codebase structure
Elimination of complex proxy setups
Streamlined deployment

But the most powerful benefit? It enables Server-Side Rendering out of the box.

How StartER Implements SSR with Express and Vite

The key to StartER's SSR implementation is how it integrates Vite's middleware mode with Express while leveraging React Router's static rendering capabilities.

The Core Structure

.
├── index.html
├── server.ts             # Main application server
└── src
    ├── entry-client.tsx  # Mounts the application on a DOM element
    ├── entry-server.tsx  # Renders the application using Vite's SSR API
    └── react
        └── routes.tsx    # Entry point for React code (client/server agnostic)

This structure separates the concerns while maintaining a cohesive application architecture.

Setting Up the Development Server

The magic starts in server.ts where we configure Vite in middleware mode:

import express from "express";
import { createServer as createViteServer } from "vite";

const app = express();
const isProduction = process.env.NODE_ENV === "production";

if (!isProduction) {
  // Create Vite server in middleware mode
  const vite = await createViteServer({
    server: { middlewareMode: true },
    appType: "custom",
  });

  // Use vite's connect instance as middleware
  app.use(vite.middlewares);

  app.use(/(.*)/, async (req, res, next) => {
    // Handle SSR rendering
    // (We'll explore this next)
  });
}

By using middlewareMode: true and appType: "custom", we tell Vite to let our Express server take control while still providing all its development features.

Server-Side Rendering Implementation

The real SSR magic happens in the catch-all route handler and the entry-server.tsx file. StartER uses React Router's static handlers and renderToPipeableStream for efficient rendering with Suspense support:

app.use(/(.*)/, async (req, res, next) => {
  const url = req.originalUrl;
  const indexHtml = fs.readFileSync("index.html", "utf-8");

  // Transform HTML with Vite plugins
  const template = await vite.transformIndexHtml(url, indexHtml);

  // Load the server entry module
  const { render } = await vite.ssrLoadModule("/src/entry-server");

  // Render the app HTML
  await render(template, req, res);
});

And in entry-server.tsx:

import { Transform } from "node:stream";
import { renderToPipeableStream } from "react-dom/server";
import { createStaticHandler, createStaticRouter, StaticRouterProvider } from "react-router";

import routes from "./react/routes";

const { query, dataRoutes } = createStaticHandler(routes);

export const render = async (template, req, res) => {
  // Get routing context
  const context = await query(
    new Request(`${req.protocol}://${req.get("host")}${req.originalUrl}`)
  );

  // Create a static router for SSR
  const router = createStaticRouter(dataRoutes, context);

  // Stream the rendered content
  const { pipe } = renderToPipeableStream(
    <StaticRouterProvider router={router} context={context} />
  );

  // Respond with streamed HTML
  res.status(200).set("Content-Type", "text/html; charset=utf-8");

  const [htmlStart, htmlEnd] = template.split("<!--ssr-outlet-->");
  res.write(htmlStart);

  const transformStream = new Transform({
    transform(chunk, encoding, callback) {
      res.write(chunk, encoding);
      callback();
    },
  });

  pipe(transformStream);
  transformStream.on("finish", () => {
    res.end(htmlEnd);
  });
};

This streaming approach has several benefits:

Support for React's <Suspense> on the server
Faster Time-To-First-Byte (TTFB)
Progressive rendering of content
Better user experience, especially on slower connections

Production Deployment

For production, StartER uses a two-part build process:

{
  "scripts": {
    "build:client": "vite build --outDir dist/client",
    "build:server": "vite build --outDir dist/server --ssr src/entry-server"
  }
}

The server code then loads the pre-built SSR bundle in production mode instead of using Vite's development-time ssrLoadModule.

Why Choose StartER for Your Next Project?

StartER is more than just an SSR implementation – it's a complete web application framework designed for educational purposes that doesn't sacrifice power or flexibility.

Key Benefits:

Educational Focus: Perfect for beginners and those advancing their skills
Seamless Development: One server approach eliminates complexity
Modern Stack: React + Express + Vite + SSR
Production Ready: Optimized build process for deployment
Best Practices: Combines the best packages in the JS ecosystem

Whether you're learning web development or building a production application, StartER provides a solid foundation that lets you focus on what matters – building your application features.

Get Started with StartER

Ready to try this "one server" approach for your next React + Express project?

Check out StartER on GitHub and give it a star if you find it useful!

The full implementation details for the SSR functionality can be found in:

What web development challenges are you facing that StartER might help solve? Open a discussion to let me know!

[Boost]

Romain Guillemot — Fri, 11 Apr 2025 19:10:12 +0000

Sue Smith for Fastly

Mar 31 '25

We should still teach coding

#ai #llm #webdev #learning

Comments 14

4 min read

A CSS razor

Romain Guillemot — Sun, 20 Oct 2024 16:36:29 +0000

A "razor" in philosophy is a methodological principle that helps simplify complex choices by eliminating unnecessary hypotheses or options.

The most famous one is Occam's Razor, which advises not to multiply entities or hypotheses beyond necessity: choose the simplest explanation that works.

Applied to CSS, this idea would suggest streamlining our style property choices to design pages in a simple and effective manner, adopting techniques that solve layout problems without unnecessary complexity.

To apply the philosophical razor to CSS, it's about choosing the simplest and most effective solutions to solve layout problems, without overloading the code with unnecessary rules. Here's how you can structure your CSS property choices efficiently, adopting a progressive approach to maintain simplicity while handling complex layout requirements:

Prioritize the Normal Flow

The normal flow is the natural way HTML elements are arranged on the page without any specific intervention. It is the simplest foundation and should be your starting point for building a layout.

Blocks: Block-level elements (such as <section>, <p>, <h1>, etc.) stack vertically, taking up the full available width.
Inline: Inline elements (such as <strong>, <a>) line up next to each other, following the horizontal flow of text.

Always start by seeing if the basic layout can be accomplished simply by working with these natural behaviors. For example:

Adjust dimensions using max-width or max-height for containers or images only after the content is in place.
Use typography properties (font-size, line-height, etc.) to organize content.

Switch to Flexbox or Grid When Necessary

When the normal flow isn’t enough, Flexbox and CSS Grid are powerful tools for handling more complex layouts. Use them thoughtfully, avoiding unnecessary complexity in the structure:

Flexbox is ideal for one-dimensional layouts (either a row or a column):
- For instance, to center an element both horizontally and vertically within a container, display: flex and justify-content: center; align-items: center; will suffice.
- Flexbox excels at simple layouts where the relationship between elements is linear (e.g., navigation bars, aligned cards, etc.).
CSS Grid is better suited for two-dimensional layouts (arranging elements in rows and columns):
- Use Grid for more complex layouts, like image galleries or data tables.
- Grid is more powerful than Flexbox for layouts where you need to control both rows and columns simultaneously.

The idea is to introduce Flexbox or Grid only when you reach the limits of the normal flow, avoiding applying them everywhere without real need.

For more details, check out these excellent guides by Josh Comeau:

Handle Spacing with `padding` and `margin`

To organize the spaces between elements, it's essential to understand the differences between padding and margin and to apply these properties methodically:

Padding: Manages the space inside the element, between its content and its border. Use padding to add space between internal content and the edge of a container, like in a button or card.
Margin: Manages the space outside the element, between the element’s border and the surrounding elements. Use margin to space elements apart from one another within the flow.

In general, use padding for internal space and margin for external space. It’s often clearer to use margin to control spacing between independent elements and reserve padding for adjusting space inside container elements.

See this article by Nathan Curtis for visual proof: Space in Design Systems.

Use `position` Values for Layering

Positioning in CSS allows for more dynamic layouts, but it’s important to avoid overusing them. Here's how to choose between the different position values:

position: static (default): Elements are positioned based on the normal flow.
position: relative: The element stays in the normal flow but can be offset from its original position. Use it when you want to move an element slightly without affecting the flow of other elements.
position: absolute: The element is removed from the normal flow and positioned relative to its first positioned ancestor (one with position: relative, absolute, or fixed). It’s useful for layering elements or positioning something precisely within a container without influencing others.
position: fixed: Similar to absolute, but the element is positioned relative to the browser window and remains fixed while scrolling (e.g., sticky navigation bars, pop-ups).
position: sticky: A mix between relative and fixed, it allows an element to stay in the flow until a certain condition is met (e.g., when it reaches a specific scroll point, it becomes fixed). It's useful for things like navigation bars that need to remain visible after some scrolling.

Use positioning wisely for specific cases where the normal flow and Flexbox/Grid cannot meet the requirements.

A concrete example: sticky footer solved by Flexbox.

Choose Appropriate Sizes for a Fluid and Responsive Layout

To ensure that the layout remains fluid and responsive, use flexible units like:

%: Percentages are relative to the parent container's size, allowing elements to adapt to different screen sizes.
em and rem: These units are relative to the parent element’s font size (or the root element’s size for rem). They are ideal for creating adaptive sizes, especially for spacing (margin, padding) and dimensions other than 100% (width, height).
vw and vh: These units are relative to the browser window size (1 vw = 1% of the window's width, 1 vh = 1% of the height). Use them for layouts that adapt to the entire screen size.

Avoid fixed units like px unless absolutely necessary, to ensure the design stays fluid across devices.

A great use case: fluid typography.

My CSS Razor in short

Start with the normal flow: Build a layout foundation using block and inline elements, simply adjusting display, width, height.
Use Flexbox or Grid sparingly: Switch to Flexbox for one-dimensional layouts or Grid for more complex two-dimensional layouts when the normal flow is insufficient.
Handle spacing intelligently: Use margin to space elements apart and padding to manage space inside containers.
Position elements as needed: Use relative for minor adjustments, absolute or fixed for elements outside the normal flow, and keep everything else static.
Prioritize fluid units: Use relative units like %, em, rem, vw, and vh to ensure a fluid and adaptable layout.

By following this methodical approach and simplifying as much as possible, you’ll be able to design effective pages without falling into the traps of overcomplexity while ensuring code maintainability.

What is your CSS razor ?

For...else in JavaScript

Romain Guillemot — Thu, 30 Nov 2023 19:46:52 +0000

A common pattern when using a for loop is to combine it with an else statement. This is possible in many template engines, such as Twig, as shown below:

<ul>
  {% for user in users %}
    <li>{{ user.username|e }}</li>
  {% else %}
    <li><em>no user found</em></li>
  {% endfor %}
</ul>

Yet in programming languages like JavaScript, a for...else construct is not supported:

for (const user of users) {
  console.log(user.username);
} else { // ❌ this is not working
  console.log("no user found");
}

The else keyword only works in combination with the if keyword. That's the limit, but also a solution:

if (users.length > 0) {
  console.log("no user found");
} else {
  for (const user of users) {
    console.log(user.username);
  }
}

"Reversing" the logic let us approach the for...else pattern. Instead of writing the loop first then the else, we're checking the "no user" case first, to end up in the loop after the else. Here the else block only contains one statement: the for statement. We can remove some curly brackets and shorten the code:

if (users.length > 0) {
  console.log("no user found");
} else for (const user of users) {
  console.log(user.username);
}

That's the closest I get from a for...else pattern in JavaScript. What do you think? Do you see a closer one?

How to do a Modal in React: the HTML first approach

Romain Guillemot — Mon, 02 May 2022 16:32:00 +0000

Do HTML before doing CSS, or JS... or React.

First, there was a modal

This story started with a modal. I needed a modal window in a React project. As a recall, here is a good definition from wikipedia:

A modal window creates a mode that disables the main window but keeps it visible, with the modal window as a child window in front of it. Users must interact with the modal window before they can return to the parent application.

Using React, this can take the form:

<Modal trigger={<button type="button">Click me</button>}>
  Lorem ipsum in a modal
</Modal>

With a first implementation of the Modal component:

function Modal({ trigger, children }) {
  const [isOpen, setOpen] = useState(false);

  return (
    <>
      {React.cloneElement(trigger, {
        onClick: () => setOpen(true)
      })}
      {isOpen && (
        <div>
          <button
            type="button"
            onClick={() => setOpen(false)}>
            x
          </button>
          <div>{children}</div>
        </div>
      )}
    </>
  );
}

I removed the class names and the style to focus on the modal logic and semantic. That's a first issue here: the semantic.

The modal is composed with the trigger and the content of the modal window. Except the content isn't qualified as a "modal window" content. Moreover this Modal handles the trigger and the content through different mechanisms:

The trigger is a prop, waiting for an element (container + content: here a <button> with a "Click me" text).
The lorem ipsum is the content of the component, passed as a rendering node (content only: the Modal wraps the text in a <div>).

And then, there were the subcomponents

A more semantic, consistent version could be:

<Modal>
  <Modal.Trigger>Click me</Modal.Trigger>
  <Modal.Window>
    Lorem ipsum in a modal
  </Modal.Window>
</Modal>

Here the trigger and the window are in the same level, while the lorem ipsum is qualified as the modal window content. In a nutshell, this can be achieved by declaring new components Trigger and Window as properties of Modal. These are React subcomponents. Something like that:

function Modal(/* ... */) {
  /* ... */
}

function Trigger(/* ... */) {
  /* ... */
}

Modal.Trigger = Trigger;

function Window(/* ... */) {
  /* ... */
}

Modal.Window = Window;

Following our previous implementation, Trigger and Window should display the open/close buttons. Modal is a container, and should display its children:

function Modal({ children }) {
  const [isOpen, setOpen] = useState(false);

  return (
    <>
      {children}
    </>
  );
}

function Trigger({ children }) {
  /* ... */

  return (
    <button
      type="button"
      onClick={() => setOpen(true)}>
      {children}
    </button>
  );
}

Modal.Trigger = Trigger;

function Window({ children }) {
  /* ... */

  return isOpen && (
    <div>
      <button
        type="button"
        onClick={() => setOpen(false)}>
        x
      </button>
      {children}
    </div>
  );
}

Modal.Window = Window;

Except isOpen and setOpen are parts of the modal state. So they must be passed to the modal children. A complex prop drilling. Complex because first you will have to "parse" the children to retrieve Trigger and Window... Let's take the easy way out with the Context API:

const ModalContext = createContext();

function Modal({ children }) {
  const [isOpen, setOpen] = useState(false);

  return (
    <ModalContext.Provider value={{ isOpen, setOpen }}>
      {children}
    </ModalContext.Provider>
  );
}

function Trigger({ children }) {
  const { setOpen } = useContext(ModalContext);

  return (
    <button
      type="button"
      onClick={() => setOpen(true)}>
      {children}
    </button>
  );
}

Modal.Trigger = Trigger;

function Window({ children }) {
  const { isOpen, setOpen } = useContext(ModalContext);

  return isOpen && (
    <div>
      <button
        type="button"
        onClick={() => setOpen(false)}>
        x
      </button>
      {children}
    </div>
  );
}

Modal.Window = Window;

What a beauty! Or is it really?

The HTML first approach

It was. Really. Such a beauty this was added to HTML ages ago. An element with an open/close state, triggered by a child, and controlling the display of its content. There are the <details> and <summary> tags. They make our Modal become:

function Modal({ children }) {
  return <details>{children}</details>;
}

function Trigger({ children }) {
  return <summary>{children}</summary>;
}

Modal.Trigger = Trigger;

function Window({ children }) {
  return <div>{children}</div>;
}

Modal.Window = Window;

A complete demo with some style is available here: https://codepen.io/rocambille/pen/poaoKYm.

Sometimes, we want things. And sometimes, we want them so hard we start writing code. Using JS or any other language/tool/framework, because that's what we learned. Using pure CSS when possible.

Sometimes we should do HTML before doing CSS, or JS... or React. Using an HTML first approach ;)

Why you should use TypeScript: a tale of self-documented code

Romain Guillemot — Wed, 15 Jul 2020 11:20:00 +0000

Make your code the best comment ever.

The undocumented array

Let's start with a simple line of JavaScript:

const a = [];

Well... that's an array declaration: no big deal. What will be this array used for?

Hard to say without any context, plus the variable name isn't helping. Here is the context: I'm working on a side project using React and React Router (v6). Here is the real code, with a real variable name, in a file named routes.js:

const routes = [
  { path: '/foo', element: <Foo /> },
  { path: '/bar', element: <Bar /> }
];

export default routes;

Here you are: the array will list the routes of the application. Then you may use it:

import { useRoutes } from "react-router";
import routes from './routes';

export default function App() {
  return useRoutes(routes);
}

Of course, I didn't invent that pattern. I saw a similar code, and wanted to make it a template repository on GitHub. Some kind of personal React framework. Thus the array should be empty in routes.js. Indeed the template shouldn't declare any route: I don't know the application I will build from my framework.

const routes = [];

export default routes;

I will remember how it should be filled since that's my own code... at least a while.

Eagleson's law

You may have heard it:

"Any code of your own that you haven't looked at for six or more months might as well have been written by someone else."

Sure I would be thankful to myself 6 months later — or next week — if I add some comment:

/* route format: {path: '/foo', element: <Foo />} */
const routes = [];

export default routes;

It may looks ok at first glance, but looking closer it's not. Really not. First, I can't expect anyone — including me — to understand this comment. It describes something as a route format. It doesn't explain what to do with the routes array. In fact it's only useful if you already know what to do. Good enough for a reminder, but not what you would expect of a documentation.

And there is an other issue. Do you always read comments in code? I don't. Hours of code reading trained my eyes and my brain to ignore them as much as they can. I'm used to see comments as pollution between 2 lines of code.

Let's see the glass half full. Now we have a checklist to write useful documentation:

you should express it in a explicit, non-ambiguous form,
you should ensure it will be read.

"Explicit, non-ambiguous expression" doesn't look like a definition of writing, but of coding. You can't be sure any human will read what you wrote. But would you ask a program, you can always be sure it will "read" your code. So why not coding the documentation? A code version of this comment:

/* route format: {path: '/foo', element: <Foo />} */

When the best comment is the code itself

That's where TypeScript can help us. In a nutshell, you can use TypeScript to describe the type of value expected for a variable:

const anyValue = '42'; // standard JS: will never complain
const anyString: string = '42'; // ok: '42' is a string
const anyNumber: number = '42'; // no: '42' is not a number

That's for primitives. Would you need to ensure an object has specific, typed properties you can define an interface or a type alias:

interface MyInterface {
  anyString: string;
  anyNumber: number;
}

const myObject: MyInterface = {
  anyString: '42',
  anyNumber: '42', // again, wrong type !!!
};

And that's what we need. Instead of a not-sure-to-be-useful comment, we can "type" the array. This will describe its future content:

import { ReactNode } from "react";

interface MyRoute {
  path: string;
  element: ReactNode;
}

const routes: MyRoute[] = [];

export default routes;

TypeScript can't misunderstand this, and it will never forget to read it. You can try it with an invalid object:

import { ReactNode } from "react";

interface MyRoute {
  path: string;
  element: ReactNode;
}

const routes: MyRoute[] = [
  { whenToRender: '/foo', whatToRender: <Foo /> }
];

export default routes;

This will output something like that:

Type '{ whenToRender: string; whatToRender: any; }' is not assignable to type 'MyRoute'
Object literal may only specify known properties, and 'whenToRender' does not exist in type 'MyRoute'

That's how TypeScript can help you to self-document your code ;)

How to roll a dice in JavaScript?

Romain Guillemot — Tue, 30 Jul 2019 15:38:38 +0000

Let's build the ultimate dice step by step.

Last update: May 11, 2022

Math.random() as a basis

A dice is a tool providing a random integer each time you roll it. Something like that:

function rollDice() {
  return /* some randomly generated number */
}

Every programming language has a built-in random function. In JavaScript, it's Math.random:

function rollDice() {
  return Math.random();
}

That’s a good start: returning a random number. Remember Math.random is not “random enough” for serious things like cryptography, or casino games — read about Crypto.getRandomValues if that’s your business. Math.random is fair enough to roll a dice with friends. Let’s try it:

>> function rollDice() {
     return Math.random();
   }
>> rollDice();
<- 0.7367823644188911

This 0.7367823644188911 is not really what we wanted… According to documentation, Math.random returns a decimal number between 0 (inclusive) and 1 (exclusive). For a 6-sided dice, we need an integer from 1 to 6. As a first guess, you may multiply by 6:

>> function rollDice() {
     return Math.random() * 6;
   }
>> rollDice();
<- 4.3380209914241235

So we would have a random decimal number between 0 (inclusive) and 6 (exclusive). So far, so good. Next step would be to get integer values:

If 0 ≤ Math.random() * 6 < 1, return 1
If 1 ≤ Math.random() * 6 < 2, return 2
If 2 ≤ Math.random() * 6 < 3, return 3
If 3 ≤ Math.random() * 6 < 4, return 4
If 4 ≤ Math.random() * 6 < 5, return 5
If 5 ≤ Math.random() * 6 < 6, return 6

This can be done using Math.floor. Let's try again — with a for-loop to console.log multiple rolls:

>> function rollDice() {
     return Math.floor(Math.random() * 6);
   }
>> for(let i = 0; i < 5; i++) console.log(rollDice());
   5
   1
   4
   2
   0 // WTF?

Once again, not exactly what we wanted... What we get here is:

If 0 ≤ Math.floor(Math.random() * 6) < 1, return 0. Not 1.
If 1 ≤ Math.floor(Math.random() * 6) < 2, return 1. Not 2.
If 2 ≤ Math.floor(Math.random() * 6) < 3, return 2. Not 3.
If 3 ≤ Math.floor(Math.random() * 6) < 4, return 3. Not 4.
If 4 ≤ Math.floor(Math.random() * 6) < 5, return 4. Not 5.
If 5 ≤ Math.floor(Math.random() * 6) < 6, return 5. Not 6.

To get the wanted result with Math.floor, we will have to add 1 before returning:

function rollDice() {
  return 1 + Math.floor(Math.random() * 6);
}

Now we have a function to simulate our 6-sided dice :)

Yes, but… What if we want a 4-, 8-, 12- or 20-sided one?

No big deal: you can change the magic number 6 in the code for a parameter, passing the maximum value for your dice. Something like this:

function rollDice(max) {
  return 1 + Math.floor(Math.random() * max);
}

const rollDice4 = () => rollDice(4);
const rollDice6 = () => rollDice(6);
const rollDice8 = () => rollDice(8);
const rollDice12 = () => rollDice(12);
const rollDice20 = () => rollDice(20);

The ultimate dice

I was once inspired by a vision: “The Ultimate Display” by Ivan E. Sutherland, 1965. Among others, I like this quote:

There is no reason why the objects displayed by a computer have to follow the ordinary rules of physical reality with which we are familiar.

We used a parameter to replace the number of sides of our dice. Why not removing the other magic number? This ugly 1 may become an other parameter:

function rollDice(min, max) {
  return min + Math.floor(Math.random() * (max - min + 1));
}

const rollDice4 = () => rollDice(1, 4);
const rollDice6 = () => rollDice(1, 6);
const rollDice8 = () => rollDice(1, 8);
const rollDice12 = () => rollDice(1, 12);
const rollDice20 = () => rollDice(1, 20);
const rollSomeUltimateDice = () => rollDice(42, 42);

This final version allows to simulate a dice which is not starting at 1. Moreover the max allows to simulate a uniform fair dice beyond “the ordinary rules of physical reality”. Imagine a 7-sided one. You can mimic your favorite dice game following its ordinary rules. But if you can imagine one, roll a dice which would never exist in reality ;)