DEV Community: jj_ranalli

How I built Notion Playgrounds using Notion API and some Nextjs magic ✨

jj_ranalli — Mon, 17 May 2021 14:41:48 +0000

Now that the Notion API is in beta, nothing could stop me anymore from trying it out. This quickly ended up in a weird experiment called Notion Playgrounds.

Here's how I built it, using Nextjs, TailwindCSS and Nightwind to automatically generate the dark mode.

Interacting with Notion API

First of all, I created an api route to handle my Notion GET requests. In this case I was interested in retrieving the contents of a Notion page, so I needed the Retrieve block children endpoint.

I knew I wanted to build more than one page, so I built a dynamic API route that accepts a pageId as the query parameter, and returns me the corresponding object from the Notion API.

// api/notion/[pageId].ts
export default async function handler(req, res) {
  const { pageId } = req.query
  const endpointBlocks = `https://api.notion.com/v1/blocks/${pageId}/children`

  const fetcher = (url, options?) =>
    fetch(url, options).then((res) => res.json())

  const data = {
    headers: {
      Authorization: `Bearer ${process.env.NOTION_KEY}`,
      "Content-Type": "application/json",
      "Notion-Version": "2021-05-13",
    },
  }

  const blocks = await fetcher(endpointBlocks, data)
  res.status(200).json({ blocks })
}

Rendering the page & the swr magic ✨

There were 3 things I wanted:

Generate the pages statically, to make everything lightning-fast and SEO friendly
Have dynamic routes, so I could have all pages under the paths /playground/1, /playground/2, etc.
Fetching data from Notion in real-time, with a stale-while-revalidate pattern.

Dynamic routes & Static Generation

Static generation in Nextjs happens through the getStaticPaths and getStaticProps functions.

GetStaticPaths is used to get the actual paths of the page, while getStaticProps returns the props to each page – in this case the slug and the pageId props.

// pages/playground/[slug].tsx

export async function getStaticPaths() {
  return {
    paths: [
      {
        params: {
          slug: "1",
        },
      },
      {
        params: {
          slug: "2",
        },
      },
      {
        params: {
          slug: "3",
        },
      },
    ],
    fallback: false,
  }
}

export async function getStaticProps(context) {
  const slug = context.params.slug
  const pageIdArray = [
    "38fc182c459340b294fca3c99b88faae",
    "9e569a521efc4f0fa2087de12fca5e81",
    "59a5889031314f73a2c1bd268a486dff",
  ]
  const pageId = pageIdArray[slug - 1]
  return {
    props: {
      slug,
      pageId,
    },
  }
}

Rendering the data on page

Getting the data to display on website is trivial when using Nextjs and the (amazing) SWR hook.

I simply have to make an API call to the API route I built in the first step, using SWR and a fetcher function. This will return me the data to display on page, while caching and revalidating automatically.

export default function Play({ slug, pageId }) {
  const fetcher = (url, options?) =>
    fetch(url, options).then((res) => res.json())

  const { data, error } = useSWR(`/api/notion/${pageId}`, fetcher)

  return (
    // Return page using data returned from the api
  )
}

At this point I just had to render what Notion was returning from my request.

In this case, that would be an array of block objects, each containing an array of Rich text objects containing the styling properties.

Note: Some blocks appear to be unsupported at this time, and others have children blocks that would've needed to be retrieved recursively. I didn't build this feature yet, so I made sure such block returned either a line element or null.

// ...
<div className="prose">
  {!error && data ? (
    data.blocks.results.map((line, key) => {
      if (line.paragraph) {
        return (
          <p key={key}>
            {line.paragraph.text.map((t, k) => {
              return <NotionSpan key={k} t={t} />
            })}
          </p>
        )
      } else if (line.heading_1) {
        return (
          <h1 key={key}>
            {line.heading_1.text.map((t, k) => {
              return <NotionSpan key={k} t={t} />
            })}
          </h1>
        )
      }
      // ... All elements that can be contained in the block objects
      else if (
        line.type === "unsupported" &&
        line.object === "block" &&
        !line.has_children
      ) {
        return <hr key={key} />
      } else {
        return null
      }
    })
  ) : (
    <p className="text-gray-500 text-center">Ready in 3, 2, 1...</p>
  )}
</div>

To handle text styling I wanted to leverage the amazing TailwindCSS palette while automatically build a dark mode with Nightwind.

So I made a <NotionSpan> component which returns the text content of the Rich text object, wrapped in a <span> element with styling applied depending on the properties of the Rich text object.

I don't have to think about styling the dark mode because Nightwind does it automatically for me.

import { FC } from "react"

export interface NotionSpanProps {
  t: any;
}

const colors = {
  text: {
    gray: "text-gray-600",
    brown: "text-amber-700",
    orange: "text-orange-600",
    yellow: "text-yellow-600",
    green: "text-green-600",
    blue: "text-blue-600",
    purple: "text-purple-500",
    pink: "text-pink-600",
    red: "text-red-500",
  },
  bg: {
    gray: "bg-gray-200",
    brown: "bg-amber-200",
    orange: "bg-orange-200",
    yellow: "bg-yellow-200",
    green: "bg-green-200",
    blue: "bg-blue-200",
    purple: "bg-purple-200",
    pink: "bg-pink-200",
    red: "bg-red-200",
  },
}

const NotionSpan: FC<NotionSpanProps> = ({ t }) => {
  return (
    <span
      className={`
      ${t.annotations.bold ? "font-bold " : ""}
      ${
        t.annotations.code
          ? "font-medium overflow-hidden shadow-md rounded-sm py-2.5 px-5 bg-gray-100 text-indigo-600"
          : ""
      }
      ${
        t.annotations.color !== "default"
          ? t.annotations.color.includes("background")
            ? `${colors.bg[t.annotations.color.split("_")[0]]} text-gray-900 `
            : colors.text[t.annotations.color]
          : ""
      }
      ${t.annotations.italic ? "italic " : ""}
      ${t.annotations.strikethrough ? "line-through " : ""}
      ${t.annotations.underline ? "underline " : ""}`}
    >
      {t.text.link ? (
        <a href={t.text.link.url} target="_blank" rel="noopener">
          {t.text.content}
        </a>
      ) : (
        `${t.text.content}`
      )}
    </span>
  )
}

export default NotionSpan

Wrapping up

And that's it! Notion API makes it really easy to get the data of a Notion page (and databases seem to be even more powerful, can't wait to try that too!), while Nextjs + swr spectacularly handle all the complex parts giving you the best possible experience.

If you liked this post or have any question, feel free to let me know on Twitter!

And if you like this whole experiment, consider leaving a note on the Notion Playgrounds and upvoting it on Product Hunt. Thanks! 🍩

How I built the dark mode of tailwindcss.com (website + docs) in 10 minutes using Nightwind & Next.js

jj_ranalli — Tue, 16 Feb 2021 20:39:05 +0000

Nightwind is a plugin for Tailwindcss that automatically generates the dark mode of any Tailwind website, while also giving full customisation options.

jjranalli / nightwind

An automatic, customisable, overridable Tailwind dark mode plugin

From now on, I'll be creating the dark mode of well-known Tailwind websites to explore how Nightwind behaves in different cases. Especially, the effectiveness of its automatic dark mode.

What Nightwind does is essentially invert the color classes used throughout a website (for example, a bg-red-300 turns into bg-red-600). Thanks to the curated Tailwind color palette, this usually results in a good-looking, coherent dark mode.

// Detect dark theme var iframe = document.getElementById('tweet-1361678659833237509-86'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1361678659833237509&theme=dark" }

I picked tailwindcss.com as the first one, as I felt it would've been the most challenging given the complexity and extensive use of color classes throughout the websites.

You can check the dark version of the homepage and the whole documentation here -> https://night-tailwindcss.vercel.app (press the Nightwind toggle in the navbar)

How I did it

1. Set up Nightwind in next.js, using 'next-themes'

I use ThemeProvider to manage light and dark modes, setting the storageKey parameter to 'nightwind-mode' to make sure the chosen mode persists.

// _app.js
import { ThemeProvider } from "next-themes"

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider
      attribute="class"
      storageKey="nightwind-mode"
      defaultTheme="system" // default "light"
    >
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

export default MyApp

In _document.js I simply add the "nightwind" class to the Html element, which is used by Nightwind to manage transitions between modes.

// _document.js
import Document, { Html, Head, Main, NextScript } from "next/document"

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    return { ...initialProps }
  }

  render() {
    return (
      <Html className="nightwind">
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default MyDocument

2. Set up a toggle

import { useTheme } from "next-themes"

export default function Toggle() {
  const { theme, setTheme } = useTheme()

  const toggle = () => {
    if (!document.documentElement.classList.contains("dark")) {
      setTheme("dark")
    } else {
      setTheme("light")
    }
  }

  return <button onClick={toggle}>Toggle</button>
}

3. Add Nightwind into Tailwind.config.js

Finally, I specify what colorClasses and variants I want Nightwind to invert, as well as add the "typography: true" option to invert all colors used by the typography plugin (used in the tailwind documentation).

module.exports = {
  darkMode: "class",
  theme: {
     nightwind: {
       typography: true,
       colorClasses: ['gradient', 'ring', 'ring-offset', 'divide', 'placeholder'],
     },
  variants: {
    nightwind: ['group-hover', 'active', 'focus'],
  },
  plugins: [require("nightwind")],
}

Note: There are also some minor modifications that were made to make everything work seamlessly. You can explore the full commit here

To learn more about Nightwind, I suggest you visit:

Thanks for reading! And if you have any suggestion about what other Tailwind website I should create the dark mode for, please let me know! :)

Introducing Nightwind: a Tailwind CSS plugin to enhance dark mode 🌘

jj_ranalli — Thu, 21 Jan 2021 16:34:48 +0000

Tailwind 2.0 introduced the long-awaited dark mode, which makes it easy to add a dark mode to your tailwind website by simply adding 'dark:' color classes.

However, there are some downsides that can make the experience not ideal. Specifically:

Each 'dark:' variant needs to be specified for every color you want to be switched (supposedly all of them, which can be quite a lot);
You need to come up with each 'dark:' color from scratch (which can take up a considerable effort);
The number of color classes in your markup may sharply increase, affecting readability while making it harder to achieve & maintain consistency in your design;
You still need to take care of the usual setup in order to correctly implement dark mode (no light flicker, persisting on update).

Nightwind addresses all of these, adding some perks to the original Tailwind implementation. Its aim is to make it easy to set up and fully manage dark mode.

At the same time it gives you many customisation options, while keeping everything tidy in your tailwind.config.js.

With just a couple of lines of code you end up with a fully functioning dark theme, often without having to write or think of a single 'dark:' class.

In other words, it makes dark mode fun.

jjranalli / nightwind

An automatic, customisable, overridable Tailwind dark mode plugin

You can see Nightwind in action here: https://nightwindcss.com

The Tailwind CSS debate on writing classes in the markup is still quite lively today. And one of the main critics surrounding dark mode has been to further exacerbating the problem.

// Detect dark theme var iframe = document.getElementById('tweet-1345794974370193409-498'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1345794974370193409&theme=dark" }

While I'm not here to fuel the fire, I also share the feeling that 'dark:' classes can often end up unnecessarily polluting the markup. Also, dark mode looks less appealing once you realise you need to write a 'dark:' class for each and every one of the color classes you've used.

And if you care about consistency (you probably should), just looking at an html made like this can feel oppressing. Which is not good.

So, with that in mind, let me introduce the feature that sparked the birth of Nightwind.

Automatic dark mode

One of the things I love most about Tailwind is its amazingly curated, weighted color palette. So one day I lazily thought:

What if I reversed the color weights when switching from light to dark mode?

(It worked much better than I thought)

Here all -50 colors are getting switched with -900, -100 with -800, -200 with -700, etc.

Watching a coherent dark mode appear without doing absolutely anything (no 'dark:' classes, no setup) is quite fascinating to me. Especially automatic dark gradients ✨

How does it work: Nightwind relies on a fixed 'nightwind' class to manage transitions, and a toggled 'dark' class applied on a top level element in the DOM, typically the root element.

But while the automatic dark theme Nightwind generates can indeed work out-of-the-box in some cases, it's not that easy to make a truly effective dark mode. Adam explained this matter in detail in the following thread:

// Detect dark theme var iframe = document.getElementById('tweet-1350454882059358208-521'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1350454882059358208&theme=dark" }

Personally, I like to use the automatic dark mode to do the guesswork and heavy lifting for me. I can then focus my whole attention on fine-tuning colors and making design choices.

Not having to start from scratch makes it remarkably fast (and fun imho).

In other words the aim of this feature is not to be perfect, but rather to give a good starting point for your customization.

Built around customization

Each color hue appears inherently different to the eye due to their perceived brightness (Refactoring UI is a great read on this matter), so color inversion behaves differently depending if you're doing it on a blue (low perceived brightness) or a yellow (high perceived brightness).

Moreover, as stated by Adam in the thread above, there are some occasion where simply inverting a color isn't desirable. Depending on the purpose of a UI element, you may want to use a different shade - or even a different color altogether.

And then, even subjectivity plays a huge role. What may look good to me, could look bad to you or may not fit your use case.

Which is why Nightwind is designed to be fully customisable, without making it harder to use.

A full list of the available customisation options can be found on the Github repository.

Here are the main aspects that makes it easy to craft your own dark theme.

Custom colors

If you add your custom colors in tailwind.config.js using number notation, Nightwind will treat them the same way as Tailwind's colors when switching into dark mode. No additional setup required.



// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#caf0f8", // becomes primary-900 in dark mode
          300: "#90e0ef", // becomes primary-600 in dark mode
          600: "#0077b6", // becomes primary-300 in dark mode
          900: "#03045e", // becomes primary-50 in dark mode
        },
      },
    },
  },
  // ...
}

Color mappings

Color mappings allow you to fine-tune your dark theme, change colors in batch and control how Nightwind behaves in dark mode.

You can map them using individual colors (in hex '#fff' or Tailwind-inspired color codes 'red.100'), or color classes (such as 'blue' or 'primary')

How would it look if all “rose” became “blue” in dark mode?

That's 1 line in Nightwind:



// tailwind.config.js
module.exports = {
  theme: {
    nightwind: {
      colors: {
        rose: "blue",
      },
    },
  },
}

Or consider the following snippet, here I'm using a hybrid mapping to not only turn all 'rose' colors into 'blue', but also to turn rose-200 colors into yellow-300.



// tailwind.config.js
module.exports = {
  theme: {
    nightwind: {
      colors: {
        white: "gray.900",
        black: "gray.50",
        yellow: "primary",
        rose: {
          default: "blue",
          200: "yellow.300",
        },
      },
    },
  },
  // ...
}

And this is what happens to your rose palette (you can also check it out on nightwindcss.com)

Overrides and the 'nightwind-prevent' class

Sometimes though, you may still wish to override some settings for a specific element.

You can easily do it in Nightwind using the default 'dark:' variant directly in your markup. Just as you would normally do in Tailwind.

And if you want an element to look exactly the same in both light and dark modes, just add a 'nightwind-prevent' class to it.

Final considerations

A cleaner HTML is a better HTML

One of the upsides of setting up dark mode this way is to write much fewer “dark:” classes, which instead go in tailwind.config.js.

This makes it easy to experiment or implement changes, while keeping your dark mode consistent.

Helper functions

To correctly implement dark mode, you may want to avoid the dreaded flicker and make the chosen mode persist on update.

There's usually some additional setup to be done, which is why Nightwind comes together with some helper functions that address these common problems.

That way you can get up and running in a matter of seconds by adding a script, or choose to use your own implementation.

Wrapping up

Nightwind is still getting frequently updated, so if you're interested in the space make sure to keep an eye on the repo to know what's going on.

And if you decide to try it out, I'd love to know what you think! So feel free to reach out to me on Twitter to let me know, or if you have any question.

Happy dark mode!