A Literate Next.js Template written in Org Mode

Introduction

What is this? This is an experiment looking at how literate programming and modern web development could work. Specifically, this is a literate Next.js template written in Emacs’ org-mode.

Literate programming means that the source code and the documentation are interwoven together and org-mode is the technology I am using to weave them together.

At the end of following this template you will have a Next.js Template with typescript and tailwind ready to go. The advantage of using this template is you be able to execute each step as you read the documentation and know what the code you are getting is supposed to do for you.

However, because the org source blocks don’t have as much functionality – autocomplete, auto-formatting, etc. – after reading through and executing this starter, it is worth assessing whether or not it is worth the loss of that functionality to continue editing in this document after you use it to jump start your project.

Getting Started

First download this org file to the root of an empty folder where you want your Next.js project to get set up. Then open the file using Emacs (most versions of Emacs include org-mode, which also as of version 7.0 includes org-babel).

You can edit the name and description of the project here. These code blocks get pulled into and written to the package.json file.

"name": "literate-next-org-mode"

"description": "A literate next.js starter written in org-mode. Includes Tailwind CSS, Typescript, and Next-SEO!"

Installing Next

First we’re going to install next, react, and react-dom.

(Put your cursor in Emacs into the code block below and execute it by pressing C-c C-c.)

yarn add next react react-dom

Next we’re going to need to add the following scripts to package.json

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
}

These scripts refer to the different stages of developing an application:

dev - Runs next dev which starts Next.js in development mode build - Runs next build which builds the application for production usage start - Runs next start which starts a Next.js production server

Next.js is built around the concept of pages. A page is a React Component exported from a .js, .jsx, .ts, or .tsx file in the pages directory.

Pages are associated with a route based on their file name. For example pages/about.js is mapped to /about. You can even add dynamic route parameters with the filename.

Create a pages directory and a styles directory inside your project. (Simply press C-c C-c with your cursor in this code block)

mkdir pages
mkdir styles

Installing Tailwind

yarn add tailwindcss@latest postcss@latest autoprefixer@latest

tailwind.config.js

module.exports = {
  purge: ['./pages/**/*.js', './components/**/*.js'],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

postcss.config.js

Tailwind is a PostCSS plugin and Next.js supports using PostCSS out of the box. This file specifies which PostCSS plugins we’re going to use.

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Installing Typescript

Next.js provides an integrated TypeScript experience out of the box.

To get started, install typescript and dependencies (again place your cursor inside this source block and press C-c C-c to execute it):

yarn add --dev typescript @types/react @types/node

tsconfig.json

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve"
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": [
    "node_modules"
  ]
}

next-env.d.ts

/// <reference types="next" />
/// <reference types="next/types/global" />

Installing and Configuring Next-SEO

yarn add next-seo

We’re going to preload some default values into next-seo

export default {
  title: "My Title",
  titleTemplate: "%s | Title",
  description: "This is the description of my site",
  favicon: "/favicon.ico",
  openGraph: {
    type: "website",
    locale: "en_US",
    url: "https://example.com",
    site_name: "SiteName",
  },
};

Next we’re going to import it and add our default SEO to our _app.tsx

_app.tsx

Next.js uses the App component to initialize pages. We’re going to override it so that we can control the page initialization. This is useful because it allows us to among other things, add global CSS - we’re including Tailwind (See Installing Tailwind for more). We’re also using next-seo to provide our default SEO values.

import "../styles/globals.css";
import { AppProps } from "next/app";
import { DefaultSeo } from "next-seo";
import SEO from "../next-seo.config.js";

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      <DefaultSeo {...SEO} />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Pages

Home Page

Now to get started we’re going to populate ./pages/index.js with the following basic React component:

function HomePage() {
  return (
    <>
      <h1 className="text-xl text-blue-800">
        Welcome to my Next.js Website written in Org-Mode.
      </h1>
      <h2 className="text-lg text-red-400">This is really neat!</h2>
    </>
  );
}

export default HomePage;

In order to get this source code from this org document to our project we need to tangle our code. To do that just run M-x org-babel-tangle in Emacs. This will write all the code blocks to the file system. (Note that this org file is set up to automatically tangle on save)

Now, in order to view your application in the browser just open a terminal and start the development server

yarn dev

Styles

Right now the only styles are the Tailwind styles which we’ve added to ./styles/globals.css and imported in _app.js

@tailwind base;
@tailwind components;
@tailwind utilities;

Appendix

Here are where other parts of the configuration files are kept.

package.json

Here you can edit the version, description, and dependency versions for the package.json:

{
  <<project-name>>,
  "version": "0.0.4",
  <<project-description>>,
  "license": "MIT",
  "dependencies": {
    "autoprefixer": "^10.2.3",
    "postcss": "^8.2.4",
    "tailwindcss": "^2.0.2",
    "next": "^10.0.5",
    "next-seo": "^4.17.0",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  },
  <<project-scripts>>,
     "devDependencies": {
    "@types/node": "^14.14.22",
    "@types/react": "^17.0.0",
    "typescript": "^4.1.3"
  }
}

Resources

• I went through the Next.js documentation and followed the “manual” instructions
• Tailwind CSS Next.js installation documentation
• Org-mode documentation on Source Code blocks

Local Variables