Expose SDK in NPM package (simple-icons#8077)

.dockerignore

@@ -6,3 +6,4 @@ npm-debug.log
 /index.js
 /index.mjs
 /index.d.ts
+/sdk.js

.gitignore

@@ -2,6 +2,7 @@
 /index.js
 /index.mjs
 /index.d.ts
+/sdk.js
 
 # Ignore all files in the icons folder
 icons/*
@@ -21,6 +22,8 @@ yarn.lock
 # Dependency directories
 node_modules/
 
+# Generated files
+*.tgz
 
 ### macOS ###
 # General

.npmignore

@@ -12,3 +12,6 @@
 !index.mjs
 !index.d.ts
 !types.d.ts
+!sdk.mjs
+!sdk.js
+!sdk.d.ts

.prettierignore

@@ -13,3 +13,4 @@ scripts/build/templates/*.js
 index.js
 index.mjs
 index.d.ts
+sdk.js

.svglintrc.mjs

@@ -4,7 +4,7 @@ import {
   getDirnameFromImportMeta,
   htmlFriendlyToTitle,
   collator,
-} from './scripts/utils.js';
+} from './sdk.mjs';
 import svgpath from 'svgpath';
 import svgPathBbox from 'svg-path-bbox';
 import parsePath from 'svg-path-segments';

CONTRIBUTING.md

@@ -396,3 +396,22 @@ Then, start a Docker container for simple-icons and attach to it:
 ```shell
 docker run -it --rm --entrypoint "/bin/ash" simple-icons
 ```
+
+## Developing Third-Party Extensions
+
+A SDK is included in the `simple-icons/sdk` entrypoint of the npm package to make it easier the development of third party extensions with Javascript and Typescript.
+
+```typescript
+import { getIconsData, type IconData } from 'simple-icons/sdk';
+
+const iconsData: IconData[] = getIconsData();
+```
+
+```javascript
+import { getIconsData } from 'simple-icons/sdk';
+
+/* @typedef {import("./simple-icons/sdk").IconData} IconData */
+
+/* @type {IconData[]} */
+const iconsData = getIconsData();
+```

package.json

@@ -25,7 +25,25 @@
     },
     "./icons/*": [
       "./icons/*"
-    ]
+    ],
+    "./sdk": {
+      "import": {
+        "types": "./sdk.d.ts",
+        "default": "./sdk.mjs"
+      },
+      "module": {
+        "types": "./sdk.d.ts",
+        "default": "./sdk.mjs"
+      },
+      "require": {
+        "types": "./sdk.d.ts",
+        "default": "./sdk.js"
+      },
+      "default": {
+        "types": "./sdk.d.ts",
+        "default": "./sdk.js"
+      }
+    }
   },
   "sideEffects": false,
   "repository": {

scripts/add-icon-data.js

@@ -1,4 +1,3 @@
-import fs from 'node:fs/promises';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import getRelativeLuminance from 'get-relative-luminance';
@@ -7,11 +6,10 @@ import {
   collator,
   getJsonSchemaData,
   getIconsDataString,
-  getIconDataPath,
-  writeIconsData,
   titleToSlug,
   normalizeColor,
-} from './utils.js';
+} from '../sdk.mjs';
+import { writeIconsData } from './utils.js';
 
 const hexPattern = /^#?[a-f0-9]{3,8}$/i;
 

scripts/build/package.js

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 /**
  * @fileoverview
- * Compiles our icons into static .js files that can be imported in the browser
- * and are tree-shakeable. The static .js files go in icons/{filename}.js. Also
- * generates an index.js that exports all icons by title, but is not
- * tree-shakeable
+ * Simple Icons package build script.
  */
 
 import { promises as fs } from 'node:fs';
@@ -19,7 +16,7 @@ import {
   getIconsData,
   getDirnameFromImportMeta,
   collator,
-} from '../utils.js';
+} from '../../sdk.mjs';
 
 const __dirname = getDirnameFromImportMeta(import.meta.url);
 
@@ -29,6 +26,8 @@ const rootDir = path.resolve(__dirname, '..', '..');
 const iconsDir = path.resolve(rootDir, 'icons');
 const indexJsFile = path.resolve(rootDir, 'index.js');
 const indexMjsFile = path.resolve(rootDir, 'index.mjs');
+const sdkJsFile = path.resolve(rootDir, 'sdk.js');
+const sdkMjsFile = path.resolve(rootDir, 'sdk.mjs');
 const indexDtsFile = path.resolve(rootDir, 'index.d.ts');
 
 const templatesDir = path.resolve(__dirname, 'templates');
@@ -68,10 +67,9 @@ const build = async () => {
       licenseToObject(icon.license),
     );
   };
-  const writeJs = async (filepath, rawJavaScript) => {
-    const { code } = await esbuildTransform(rawJavaScript, {
-      minify: true,
-    });
+  const writeJs = async (filepath, rawJavaScript, opts = null) => {
+    opts = opts === null ? { minify: true } : opts;
+    const { code } = await esbuildTransform(rawJavaScript, opts);
     await fs.writeFile(filepath, code);
   };
   const writeTs = async (filepath, rawTypeScript) => {
@@ -119,6 +117,11 @@ const build = async () => {
     '',
   )}`;
   await writeTs(indexDtsFile, rawIndexDts);
+
+  // create a CommonJS SDK file
+  await writeJs(sdkJsFile, await fs.readFile(sdkMjsFile, UTF8), {
+    format: 'cjs',
+  });
 };
 
 build();

scripts/get-filename.js

@@ -5,7 +5,7 @@
  * icon SVG filename to standard output.
  */
 
-import { titleToSlug } from './utils.js';
+import { titleToSlug } from '../sdk.mjs';
 
 if (process.argv.length < 3) {
   console.error('Provide a brand name as argument');

scripts/lint/jsonlint.js

@@ -4,14 +4,10 @@
  * CLI tool to run jsonschema on the simple-icons.json data file.
  */
 
-import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { Validator } from 'jsonschema';
-import {
-  getDirnameFromImportMeta,
-  getIconsData,
-  getJsonSchemaData,
-} from '../utils.js';
+import { getDirnameFromImportMeta, getIconsData } from '../../sdk.mjs';
+import { getJsonSchemaData } from '../utils.js';
 
 const icons = await getIconsData();
 const __dirname = getDirnameFromImportMeta(import.meta.url);

scripts/lint/ourlint.js

@@ -6,7 +6,7 @@
  */
 
 import fakeDiff from 'fake-diff';
-import { getIconsDataString, normalizeNewlines, collator } from '../utils.js';
+import { getIconsDataString, normalizeNewlines, collator } from '../../sdk.mjs';
 
 /**
  * Contains our tests so they can be isolated from each other.

scripts/release/bump-version.js

@@ -6,7 +6,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { getDirnameFromImportMeta } from '../utils.js';
+import { getDirnameFromImportMeta } from '../../sdk.mjs';
 
 const __dirname = getDirnameFromImportMeta(import.meta.url);
 

scripts/release/update-cdn-urls.js

@@ -7,7 +7,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { getDirnameFromImportMeta } from '../utils.js';
+import { getDirnameFromImportMeta } from '../../sdk.mjs';
 
 const __dirname = getDirnameFromImportMeta(import.meta.url);
 

scripts/release/update-slugs-table.js

@@ -7,7 +7,7 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { getIconsData, getIconSlug } from '../utils.js';
+import { getIconsData, getIconSlug } from '../../sdk.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

scripts/release/update-svgs-count.js

@@ -7,7 +7,7 @@
  */
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { getDirnameFromImportMeta, getIconsData } from '../utils.js';
+import { getDirnameFromImportMeta, getIconsData } from '../../sdk.mjs';
 
 const regexMatcher = /Over\s(\d+)\s/;
 const updateRange = 100;