fake-tag

fake-tag

A fake template literal tag to trick syntax highlighters, linters and formatters into action. Interpolations and escapes are tested.

Installation

For Node.js, to install fake-tag with npm, run:

npm install fake-tag

For Deno and browsers, an example import map:

{
  "imports": {
    "fake-tag": "https://unpkg.com/fake-tag@5.0.0/fakeTag.mjs"
  }
}

Then, import and use the template literal tag fakeTag.

Examples

Tagging a GraphQL SDL string with gql:

import gql from "fake-tag";

const typeDefs = gql`
  "A foo."
  type Foo {
    "The \`Foo\` ID."
    id: ID!
  }
`;

Requirements

Supported runtime environments:

• Node.js versions ^14.17.0 || ^16.0.0 || >= 18.0.0.
• Deno.
• Browsers matching the Browserslist query > 0.5%, not OperaMini all, not dead.

Non Deno projects must configure TypeScript to use types from the ECMAScript modules that have a // @ts-check comment:

• compilerOptions.allowJs should be true.
• compilerOptions.maxNodeModuleJsDepth should be reasonably large, e.g. 10.
• compilerOptions.module should be "node16" or "nodenext".

Exports

The npm package fake-tag features optimal JavaScript module design. These ECMAScript modules are exported via the package.json field exports:

• fakeTag.mjs

FAQ

Why not comment tags?

A comment tag looks like this:

const QUERY = /* GraphQL */ `
  {
    foo
  }
`;

They are far superior to a fake tag:

• No dependency to manage.
• No inconvenient imports.
• No bundle size bloat.
• No runtime overhead.

Unfortunately not all tools support them yet. prettier has since v1.13.0, but eslint-plugin-graphql at v3.1.0 still doesn’t.

Why not String.raw?

This may be temptingly simple:

const gql = String.raw;
const QUERY = gql`
  {
    foo
  }
`;

However, it doesn’t unescape characters. For the usage example, if you console.log(typeDefs) before and after replacing the import with const gql = String.raw you will see the difference in the type description markdown:

    "A foo."
    type Foo {
-     "The `Foo` ID."
+     "The \`Foo\` ID."
      id: ID!
    }

Changelog

5.0.0

Major

• Updated Node.js support to ^14.17.0 || ^16.0.0 || >= 18.0.0.
• Updated dev dependencies, some of which require newer Node.js versions than previously supported.
• Removed the package main field.
• Use the node: URL scheme for Node.js builtin module imports in tests.

Patch

• Updated jsconfig.json:
  • Set compilerOptions.maxNodeModuleJsDepth to 10.
  • Set compilerOptions.module to nodenext.
• Updated ESLint config.
• Updated GitHub Actions CI config:
  • Run tests with Node.js v14, v16, v18.
  • Updated actions/checkout to v3.
  • Updated actions/setup-node to v3.
• Removed the now redundant not IE > 0 from the Browserslist query.
• Revamped the readme:
  • Removed the badges.
  • Added a “Requirements” section.
  • Added information about Deno, import maps, TypeScript config and optimal JavaScript module design.