DEV Community: Blank Particle

Creating a tailwind plugin shouldn't be that hard, right?

Blank Particle — Sat, 09 Dec 2023 06:44:56 +0000

Recently, I came across a site called RealtimeColors.com, It's a pretty cool site that helps you choose colors for your site and visualize them on a real site.

The site provides an export for tailwind, but it's tedious to copy and set up everything and change the colors later. So, as a developer myself, I spent 2 days automating a task that would hardly take 2 minutes of my life. The result is tailwind-plugin-realtime-colors. Please consider giving a star to the repo.

Sit tight, as this is gonna be a long ride.

Creating Tailwind Plugins

TailwindCSS provides a Plugin API. It is not that intuitive, to be honest. Here is a snippet they provide on their site.

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
      // Add your custom styles here
    }),
  ]
}

At a glance you can't understand what the f*ck is going on, but here is what It actually means in ES6 syntax.

// tailwind.config.ts
import plugin from "tailwindcss/plugin";

const somePlugin = plugin(({ addUtilites }) => {
  addUtilites(/*...*/);
  //...
});

export default {
  // ...
  plugins: [somePlugin()],
  // ...
};

Actually creating the plugin

So, I started working on the plugin in a file called realtime-colors.ts in the project directory. I wanted to achieve this kind of configuration.

import realtimeColors from "./realtime-colors.ts";

export default {
  //...
  plugins: [realtimeColors("https://www.realtimecolors.com/?colors=e8eef4-050709-a1b9d1-75393b-ab9d54", /*Some config options*/)],
  //...
};

I wrote some type definitions and function signatures for the starter.

// realtime-colors.ts
import plugin from "tailwindcss/plugin";

type HexColor = `#${string}`;
type Plugin = ReturnType<typeof plugin>;
export type RealtimeColorOptions = {
  colors: {
    text: HexColor;
    background: HexColor;
    primary: HexColor;
    secondary: HexColor;
    accent: HexColor;
  };
  // don't worry about these options now
  theme: boolean;
  shades: (keyof RealtimeColorOptions["colors"])[];
  prefix: string;
  shadeAlgorithm: keyof typeof availableModifiers;
};
type RealtimeColorOptionsWithoutColor = Omit<RealtimeColorOptions, "colors">;

// ...

function realtimeColors(
  config: Pick<RealtimeColorOptions, "colors"> & Partial<RealtimeColorOptionsWithoutColor>,
): Plugin;
function realtimeColors(
  url: string,
  extraConfig?: Partial<RealtimeColorOptionsWithoutColor>,
): Plugin;
function realtimeColors(
  configOrUrl: string | Pick<RealtimeColorOptions, "colors">,
  extraConfig?: Partial<RealtimeColorOptionsWithoutColor>,
): Plugin {
    // Handle the passed options and return plugin with appropiate config
}

export default realtimeColors;

If you are confused about why there are 3 functions named realtimeColors I recommend you learn function overloading.

Now I check if the first option is a string, then I parse the URL, extract the colors and combine it with the optional passed config and defaultConfig. If the first option is an object then I just combine it with defaultConfig. You can look at the actual implementation on my GitHub.

Now for the actual plugin, I have an arrow function called realtimeColorsPlugin.

const realtimeColorsPlugin = plugin.withOptions<RealtimeColorOptions>(
  (options) => ({ addBase }) => addBase(getCSS(options)),
  (options) => ({
    theme: {
      extend: {
        colors: getTheme(options),
      },
    },
  }),
);

If you want to pass options to the plugin you need to use plugin.withOptions

`getCSS` and `getTheme` function

Before we jump into getCSS and getTheme function, we need to establish some concepts.

Modifiers

A modifier is an object with keys 50|100|200|300|400|500|600|700|800|900|950, and have function with signature ([number,number,number]) => [number, number, number].

If you haven't guessed already, they take RGB colors and modifies the color.

As of version 1.1.1 of the plugin It has 2 types of modifiers, one is realtimeColors which uses the same algorithm as RealtimeColors.com to create the shades of the given colors. Personally, I don't like the shades created by this algorithm. So there is an alternative modifier called tailwind which is the default for this plugin.

You can use whatever algorithm you like, but remember the color you selected is not present in realtimeColors shades, but it is present in tailwind shades as 500.

Also, by default primary, secondary and accent are shaded. If you also want to shade text or background, you can do so by passing the colors you want to shade in shades array.

See More about the options here.

Theme

The theme option decides if the colors should automatically adapt to dark/light mode. there is no need to use dark: as the colors are assigned to CSS variables which change based on dark class on html element.

To create the alternate variant of a certain color, invertColor function is used. I didn't create this function, it was reverse-engineered from RealtimeColors.com.

`getCSS` function

This function is responsible for generating the CSS variables. So it returns nothing if theme is set to false as the colors are directly embedded in the config.

Otherwise, it generates the values to use in a CSS rgb/hsl/lch/lab color function based on the config. It also creates the shades with the specified modifiers if needed. Then the variables are injected into :root and :is(.dark):root.

The variables are just values without the color function.

:root {
  --text: 3, 32, 30;
  --background: 246, 254, 253;
  --primary-50: 0, 5, 4;
  --primary-100: 1, 14, 13;
  --primary-200: 2, 29, 25;
  --primary-300: 4, 47, 41;
  /*...*/
}
:is(.dark):root {
  /*...*/  
}

At first, I wrote my own functions for color conversion, It was a mess and they were terribly inaccurate. I suggest using an established library like color-convert to handle these tasks.

`getTheme` function

It is responsible for adding the colors in the tailwind config. If theme is set to false then it embeds the color directly in the config. Otherwise, it uses the variables from getCSS with the proper color function.

For some reason rgb doesn't support alpha values with CSS Variables. This problem doesn't happen with hsl,lch or lab. The fix is to use rgba instead of rgb. For other formats than rgba, we can also use <alpha-value> like hsl(var(--text) / <alpha-value>), even tho it works without it, but it's still recommended

And just like that you have your very own TailwindCSS Plugin. Obviously, I skipped a lot of details and implementations. You can visit my GitHub Repo for the full code.

While you are going to visit the repo, consider giving it a ⭐, It motivates me.

There is going to be a sequel to this blog on how to convert this file into an npm package, bundle it and deploy it to npmjs.com using GitHub Actions. Stay tuned for that.

it's Blank Particle, Signing Out 👋

Redirecting Your Domains using Cloudflare

Blank Particle — Sun, 13 Aug 2023 10:16:06 +0000

I was not available for some time, so I haven't written about anything in a long time, recently I bought a new domain so I had to redirect my old domain and its subdomains to my new domain, This small blog is about how to do that.

You can expect regular blog posts from me starting in September.

I recently had to redirect my .me domain to .in domain, so I had to do Cloudflare domain redirects. Here is how to do it.

Adding DNS Records

First you need to add some DNS Records, follow this table and create new records or edit your existing records.

Type	Name	Content	Proxy Status	TTL
A	`*`	192.0.2.1	Proxied	Auto
A	`@`	192.0.2.1	Proxied	Auto

You should not edit non-conflicting Records until you know what you are doing

Setting Up Page Rules

Once you have DNS setup, go to Rules > Page Rules, Add a new rule with the config defined below,

URL: *olddomain.com/*
Setting: Forwarding URL
Status Code: 301 / 302
Destination URL: https://$1newdomain.com/$2

Now save the page rule and enable if already not enabled, This might take up to an hour to reflect on all devices due to DNS Caches.

Effects

With this config all URLs and subdomains of olddomain.com will be redirected to newdomain.com

From	Redirected To
`https://olddomain.com`	`https://newdomain.com`
`https://olddomain.com/anypage?with=query_string`	`https://newdomain.com/anypage?with=query_string`
`https://www.olddomain.com`	`https://www.newdomain.com`
`https://anything.olddomain.com`	`https://anything.newdomain.com`

Sources

How I created a Spotify Lyrics API using Cloudflare Workers

Blank Particle — Mon, 12 Jun 2023 08:39:55 +0000

Context: I was Working on my Portfolio when it occurred to me that I could add a custom Spotify Widget to my website, So like most developers, I ignored every prebuilt widget and tried creating my own. I thought it would be cool if I could show the lyrics of the song that I am currently listening to. But unfortunately, Spotify doesn't provide any kind of lyrics API. So I decided to take matters into my own hands and make one myself.

PS: I forgot about my Portfolio 😅, But now I at least have the API.

You can visit my unfinished portfolio and try out Spot-API yourself.

Finding a Solution

So, as any good developer, I went to read the docs of Spotify, and I have only one thing to say, "those are bad". I couldn't find any reference to lyrics in entire docs.

Doing a little bit of Googling

So, I just googled it and found this on StackOverflow. We can request this to get the lyrics of any given track_id.

const url = `https://spclient.wg.spotify.com/color-lyrics/v2/track/${track_id}?format=json&vocalRemoval=false`;
let req = await fetch(url, {
  headers: {
    "app-platform": "WebPlayer",
    authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

let lyrics = await req.json();
console.log(lyrics);

Finding Access Token

As you can see this request would work if we had the ACCESS_TOKEN, and let me tell you that none of the tokens listed in Spotify docs works.

So, the solution is to do a little bit of observation in Spotify Web Player's Network tab, We can see that we can get an access token by requesting https://open.spotify.com/get_access_token, but this token is very short-lived. It expires after an hour.

The response looks like this,

{
  "clientId": "some-hexadecimal-number",
  "accessToken": "some-random-token",
  "accessTokenExpirationTimestampMs": 1686510137991,
  "isAnonymous": false
}

Renewing Access Token

We could just request again, but trying to do that from a fetch function returns a accessToken which is anonymous, that token is not useful. So how do we get a proper accessToken?

Enter Spotify User Cookie

Spotify User Cookie known as sp_dc is a Cookie that can be used to control your whole Spotify account, it is the only way to get a token capable of using the lyrics API. But you wouldn't want this kind of thing to be embedded in your front-end code. That's why we are going to create a serverless function that can do this for us without exposing any sensitive information to the client.

Obtaining the sp_dc Cookie

To obtain a sp_dc cookie you would likely want to create a new Spotify account so that even if your cookie gets leaked it doesn't affect you. Then you need to open a Private/Incognito Tab so that you couldn't accidentally log out and invalidate your Cookie.

First Login Into your newly made account in a Private Tab
Then open DevTools by pressing Ctrl+Shift+I (or the binding specific to your OS/Browser)
Goto Application Tab in Chrome (or any other Chromium-based browser) and find the sp_dc Cookie and Copy the value, Alternatively goto Storage Tab in Firefox and do the same
Now close the Tab without logging out

Congratulations! You have obtained a Spotify User Cookie. Now this Cookie is valid for a year or until you revoke/log out of your Spotify Account. You need to keep an eye on this and act accordingly.

Minimal Implementation

After finding this I went to create a minimal solution, at that time I was working with Svelte, So I just created an Svelte Kit Project and added an API route with my findings. This Code is available in the legacy branch of my repo.

As You can see this code works within a Svelte API route.

Creating a Better Solution

As you can already tell deploying a SvelteKit App for only one API route is not the best idea. I opted in for Cloudflare Workers as I have been wanting to learn those. I also used the Hono Library as it makes handling paths easier.

So first we need to create a Cloudflare Worker Project.

pnpm create cloudflare@latest # Create a cloudflare Project

Then cd into your newly created project and install hono.

pnpm add hono

Now, open src/index.ts, delete boilerplate code and create a basic app

import { Hono } from "hono";

const app = new Hono();

app.get("/", async (ctx) => {
    ctx.text("This works!")
}

export default app;

Now run your app locally and navigate to https://localhost:8787/

pnpm wrangler dev

If all of this works you would see "This Works!" in your browser.

Now remove the "/" route and replace it with "/lyrics/:track_id", then edit the route like this.

app.get("/lyrics/:track_id", async (ctx) => {
    let { track_id } = ctx.req.params();
    ctx.text(track_id);
}

If you go to https://localhost:8787/lyrics/any-track-id then you would see "any-track-id" on the page which means we can get parameters from the requested URL.

We need to use the SPOTIFY_COOKIE safely in our app, so we need to create a .dev.vars file in the project root and our Cookie like this.

SPOTIFY_COOKIE=your-spotify-cookie

Then we need to edit our app like this and restart the dev server to have access to secret variables, its works like a .env file.

//--snip--
type Bindings = {
    SPOTIFY_COOKIE:string;
}

const app = new Hono<{Bindings: Bindings}>();
// You can access this value in a request with `ctx.env.SPOTIFY_COOKIE`

// We create these two global variables which we will need later
let ACCESS_TOKEN: string|null = null;
let ACCESS_TOKEN_EXPIRY: number = Date.now();
//--snip--

Now we can try to request a accessToken like this.

const predefinedRequestHeaders = {
  "User-Agent":
    "Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/114.0",
  Accept:
    "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
  "Accept-Language": "en-US,en;q=0.5",
  "Alt-Used": "open.spotify.com",
  "Upgrade-Insecure-Requests": "1",
  "Sec-Fetch-Dest": "document",
  "Sec-Fetch-Mode": "navigate",
  "Sec-Fetch-Site": "cross-site",
};

const raw_data = await(
  await fetch("https://open.spotify.com/get_access_token", {
    headers: {
      ...predefinedRequestHeaders,
      Cookie: `sp_dc=${ctx.env.SPOTIFY_COOKIE}`,
    },
  })
).text();

try {
  const data: AccessTokenAPIData = JSON.parse(raw_data);
  ACCESS_TOKEN = data.accessToken;
  ACCESS_TOKEN_EXPIRY = data.accessTokenExpirationTimestampMs;
} catch (e) {
  console.log(e, raw_data);
  return new Response(JSON.stringify({ error: "Unknown Error Occurred!" }), {
    headers: { "content-type": "application/json; charset=utf-8" },
    status: 500,
  });
}

Through this, we will get the ACCESS_TOKEN and ACCESS_TOKEN_EXPIRY and save those in global variables for caching. With this, we can skip requesting new tokens on every request.

if (!ACCESS_TOKEN || ACCESS_TOKEN_EXPIRY <= Date.now()) {
    // Request new token
}
// otherwise continue with old one

Also, as you have seen we need a bunch of headers in the request which are defined in predefinedRequestHeaders, without these headers we will get a 403 Forbidden error, So we need to include these with every request.

Now finally we can hit the Lyrics API and retrieve the lyrics of the song.

const url = `https://spclient.wg.spotify.com/color-lyrics/v2/track/${track_id}?format=json&vocalRemoval=false`;
const lyrics = await (
  await fetch(url, {
    headers: {
      "app-platform": "WebPlayer",
      authorization: `Bearer ${ACCESS_TOKEN}`,
    },
  })
).text();

return new Response(
  lyrics === ""
    ? JSON.stringify({ error: "Lyrics are not available for this song" })
    : lyrics,
  {
    headers: { "content-type": "application/json; charset=utf-8" },
    status: lyrics === "" ? 404 : 200,
  }
);

To get the track_id of any song you could just share the song link and use the last part of the URL or you can set up another service that will give you the currently playing song. I am not going to cover that.

And like this now we have a working Spotify Lyrics API, full code with a bunch of improvements and checks is available in my GitHub repo. Feel free to check that and suggest improvements. Also, Star my GitHub repo as it helps a ton.

The Final Part: Deployment

You can check deployment instructions on the GitHub repo, so I am not repeating that part here.

Conclusion

As this is not a part of the Offical part of Spotify API, it is advised to use this personal projects only.

Also, this is my first blog post so feel free to correct me, You can also connect to me via Discord.