DEV Community: Matthias Zaunseder

Create a zx Node.js script as binary with pkg

Matthias Zaunseder — Thu, 17 Mar 2022 16:04:19 +0000

So there is this really cool library called zx which you can use to create scripts that are replacements for bash scripts.
But one downside of it is, that now you have to have the Node.js runtime installed on the machine where this script should run. That's sad :(

But what if you could create a binary which includes your script AND the Node.js runtime?

pkg to the rescue!

But first things first, let's create a simple zx script. Please make sure that you have Node.js 16+ installed on your machine and then open a shell and type the following commands to create a new directory and initialise a Node.js project.

$ cd /my/projects
$ mkdir my-cli
$ cd my-cli
$ npm init -y

Now you should have a package.json file and in this file you have to add "type": "module" for zx to work correctly:

{
  "name": "my-cli",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
+ "type": "module"
}

Next we can add zx as a dependency:

$ npm install zx

We are ready to write our nice little script! Create a folder src and add a file index.js with this content:

// src/index.js
import { $ } from "zx";

async function main() {
  await $`date`;
}

main().catch((err) => console.log(err));

You can test it now in the shell with

$ node src/index.js

This should output the current date and time on your machine. But as we saw we have to use the node runtime to execute our script (or the zx runtime as they show in their examples). Because this is sometimes not ideal, for example if the machine doesn't have Node.js or zx installed then our script can not run there.

The solution to this problem is to pack the runtime and our script in an executable binary and then you can start your script even if the machine has no runtime installed.

For the packaging we will use the pkg library. But unfortunately pkg is not supporting ES modules which we configured by adding the "type": "module" to the package.json. So before we can use pkg we need to compile our script to a version which is not using ES modules. To do the compilation we will use esbuild. esbuild can also bundle our script into one file, so no dependencies on a node_modules folder are left in the compiled file. So let's install it.

$ npm install --save-dev esbuild

And let's add a npm script in package.json to do the compilation:

{
  "name": "my-cli",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "compile": "esbuild src/index.js --platform=node --target=node16 --bundle --outfile=dist/outfile.cjs"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "zx": "^6.0.1"
  },
  "devDependencies": {
    "esbuild": "^0.14.27"
  }
}

This npm script will execute esbuild, use src/index.js as an entrypoint and configure esbuild to output a Node.js v16+ compatible file to dist/outfile.cjs. The .cjs file ending is important because otherwise pkg tries to load our bundle with ES modules even if we have compiled them away.

So now you can try the compiling script:

$ npm run compile

You will see something like this in the shell:

> my-cli@1.0.0 compile
> esbuild src/index.js --platform=node --target=node16 --bundle --outfile=dist/outfile.cjs

  dist/outfile.cjs  439.1kb

⚡ Done in 246ms

Next up we install the pkg library and also add a npm script to execute it.

$ npm install --save-dev pkg

package.json: (don't forget the comma after the compile script)

{
  "name": "my-cli",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "compile": "esbuild src/index.js --platform=node --target=node16 --bundle --outfile=dist/outfile.cjs",
+   "package": "pkg dist/outfile.cjs --targets node16 --output dist/my-cli --debug"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "zx": "^6.0.1"
  },
  "devDependencies": {
    "esbuild": "^0.14.27",
    "pkg": "^5.5.2"
  }
}

The package script is executing pkg and uses dist/outfile.cjs as entrypoint. Also it configures that we want to have Node.js 16 as a target runtime and it should output a file dist/my-cli.

Now if you execute the package script you should hopefully see a binary in your dist folder.

$ npm run package

This outputs a lot of debugging information which you can ignore for now. But if you have problems you can see there couple of helpful infos to diagnose the issue.

Please keep in mind, that this will output a binary which is only compatible with the same operating system and processor architecture as your developer machine. So if you execute the npm run package command on a Windows machine with x64 processor, the binary will not work on a Linux or macOS machine. To work there, you would either need to change the package command to include more targets (please see the documentation for that) or execute the package command on the same OS/processor architecture.

Now in your file explorer you can already see a file dist/my-cli or dist/my-cli.exe depending on the OS you are working with. And this file is executable in the shell for example with this call:

$ ./dist/my-cli

And if everything worked you should see the current date and time 🥳

This binary file can now be used without any runtime (as long as you execute it on the same OS/processor architecture) Great!

Have fun writing great scripts which are runtime agnostic!

Photo by Markus Spiske on Unsplash

Craft CMS Live Preview with Next.js 9.3 Static Site Generation and GraphQL

Matthias Zaunseder — Sun, 15 Mar 2020 18:42:24 +0000

Next.js 9.3 was released 9th of March and has a new and exciting feature for all headless CMS users out there: Static Site Generation coupled with Preview Mode

Static Site Generation (SSG for short) allows us to generate a static site with the contents of our headless CMS during the build. The magic function which enables this is getStaticProps. There we can fetch data from any data source and Next.js will use it to generate a static site.

So this is nice, but now you have static HTML/JS/CSS, but your users of the CMS might want to see a preview of their newly created content. Then you want to dynamically render the page again so that the CMS editor can see his changes.

So I tried to combine a headless Craft CMS with a frontend written in Next.js with static site generation and working live preview. The data fetching will happen over the new GraphQL API of Craft.

First of all, you need a working Craft CMS 3.4 installation with activated GraphQL API. See the Installation guide and the GraphQL Getting Started guide for instructions.
Then you also need a running Next.js website. See the Getting Started guide.

Configuration in Next.js

I have implemented everything in TypeScript, so if you use JavaScript, you have to adjust the examples a bit.

This a simple fetch wrapper to be able to make GraphQL Requests to Craft:

utils/fetch.ts

import fetch from 'node-fetch'; // install with `npm install node-fetch`

/**
 * Fetch from Craft GraphQL API
 * @param query GraphQL Query
 * @param previewToken Optional preview token to get draft data
 */
export default async function(
  query: string,
  previewToken?: string
) {
  let craftUrl = 'http://localhost:8888/api';

  if (previewToken && previewToken !== '') {
    craftUrl += '?token=' + previewToken;
  }

  const res = await fetch(craftUrl, {
    method: 'post',
    body: query,
    headers: {
      'Content-Type': 'application/graphql',
    },
  });

  return await res.json();
}

In the page file, where you want to have SSG with a preview, you have to implement the getStaticProps function.

This fetches the data for the Homepage. In my case this is a single section called "Homepage", which has a field named "text".

pages/index.tsx

export const getStaticProps: GetStaticProps = async context => {
  const { data } = await fetch(
    `
    {
      entry(title: "Homepage") {
        ... on homepage_homepage_Entry {
          text
        }
      }
    }
    `,
    context.preview ? context.previewData?.previewToken : undefined
  );

  return {
    props: {
      data
    }
  };
};

The context.previewData.previewToken data is coming from an API route which is shown below. We only supply the previewToken to the fetch function when the context.preview field is true.

pages/api/preview.ts

import { NextApiRequest, NextApiResponse } from "next";
import fetch from "../../utils/fetch";

export default async (req: NextApiRequest, res: NextApiResponse) => {
  // (1)
  // Check for the right query params
  if (!req.query["x-craft-live-preview"] || !req.query.entryUid) {
    return res
      .status(401)
      .json({ message: "Not allowed to access this route" });
  }

  // (2)
  // Get the url from Craft for the specific entry
  const { data } = await fetch(
    `
      {
        entry(uid: "${req.query.entryUid}") {
          url
        }
      }
    `
  );

  if (!data?.entry?.url) {
    return res.status(404).json({
      message: `URL of the entry "${req.query.entryUid}" could not be fetched`
    });
  }

  // (3)
  // Set the token as preview data
  res.setPreviewData({
    previewToken: req.query.token ?? null
  });

  // (4)
  const parsedUrl = new URL(data.entry.url);

  // Redirect to the path from the fetched url
  res.writeHead(307, { Location: parsedUrl.pathname });
  res.end();
};

This function does the following:

The function expects minimum 2 query params in the URL, "x-craft-live-preview" which gets set by Craft automatically in preview mode and "entryUid" so that we have the uid of the currently previewed entry. If they are not present, we will stop the function.
We try to fetch the URL of the entry from Craft so that we can redirect to the right page.
If the query params have a token param, we will set it as preview data.
We use the URL of the Entry and redirect to the path (Next.js doesn't like the domain part of the URL)

Configuration in Craft

You have to configure your section (in my case the Homepage section) with a preview URL which points to the previously built preview API endpoint in Next.js (Next.js frontend is running under localhost:3000): http://localhost:3000/api/preview?entryUid={sourceUid}
It is important to use {sourceUid} and not {uid} because the uid could be different in draft entries, but they are not queryable.

Et voilà: A static generated homepage, which can show a live preview in Craft whenever you edit the content.

Todos

localhost:8888 for the Craft CMS and localhost:3000 for Next.js are hardcoded. This should be configured with .env files.