feat!: better support for ESM imports (#850)

* feat: supporting esm import (#824)

* feat: supporting esm import
add the exports in package.json to support esm import for js and ts

* feat: support for .js module export
adding the support for .js module exports and support for types, nextjs, framework and recipe module exports

* test: add a test to check our export mapping

* fix: update export mapping

* chore: update version number

* chore: add new related checklist item to PR template

* fix: remove unnecessary/broken entry point

* test: add explanation comment

---------

Co-authored-by: Anurag Srivastava <[email protected]>

.circleci/doUnitTests.sh

@@ -18,6 +18,15 @@ then
 fi
 coreFree=$(echo $coreFree | jq .core | tr -d '"')
 
+cd ..
+./test/testExports.sh
+if [[ $? -ne 0 ]]
+then
+    echo "export test failed... exiting!"
+    exit 1
+fi
+cd .circleci
+
 ./setupAndTestWithFreeCore.sh $coreFree $coreDriverVersion
 if [[ $? -ne 0 ]]
 then

.github/PULL_REQUEST_TEMPLATE.md

@@ -36,6 +36,7 @@
 -   [ ] If have added a new web framework, update the `add-ts-no-check.js` file to include that
 -   [ ] If added a new recipe / api interface, then make sure that the implementation of it uses NON arrow functions only (like `someFunc: function () {..}`).
 -   [ ] If added a new recipe, then make sure to expose it inside the recipe folder present in the root of this repo. We also need to expose its types.
+-   [ ] If added a new entry point, then make sure that it is importable by adding it to the `exports` in `package.json`
 
 ## Remaining TODOs for this PR
 

.gitignore

@@ -10,4 +10,6 @@ releasePassword
 .tmp
 .idea
 /test_report
+/temp_test_exports
+/temp_*
 /.nyc_output

.npmignore

@@ -18,4 +18,5 @@ examples/
 add-ts-no-check.js
 docs/
 .prettierignore
-updateLibInExample
+updateLibInExample
+testExports.sh

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [19.0.0] - 2024-06-10
+
+### Breaking changes
+
+-   Defined the entry points of the library using the "exports" field in package.json to make ESM imports more comfortable. This can cause some issues for applications using directory imports from the `lib/build` directory. In those cases we recommend adding `index.js` to the import path.
+
 ## [18.0.0] - 2024-05-23
 
 ### Breaking change

lib/ts/version.ts

@@ -12,7 +12,7 @@
  * License for the specific language governing permissions and limitations
  * under the License.
  */
-export const version = "18.0.0";
+export const version = "19.0.0";
 
 export const cdiSupported = ["5.0"];
 

package.json

@@ -1,10 +1,11 @@
 {
     "name": "supertokens-node",
-    "version": "18.0.0",
+    "version": "19.0.0",
     "description": "NodeJS driver for SuperTokens core",
     "main": "index.js",
     "scripts": {
         "test": "TEST_MODE=testing npx mocha --node-option no-experimental-fetch -r test/fetch-polyfill.mjs --timeout 500000",
+        "test-exports": "./test/testExports.sh",
         "build-check": "cd lib && npx tsc -p tsconfig.json --noEmit && cd ../test/with-typescript && npm run build",
         "build": "cd lib && rm -rf build && npx tsc -p tsconfig.json && cd ../test/with-typescript && npm run build && cd ../.. && npm run post-build",
         "pretty": "npx pretty-quick .",
@@ -27,6 +28,84 @@
         "type": "git",
         "url": "git+https://github.com/supertokens/supertokens-node.git"
     },
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./index": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./index.js": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./framework/*": {
+            "types": "./framework/*/index.d.ts",
+            "default": "./framework/*/index.js"
+        },
+        "./framework/*/index": {
+            "types": "./framework/*/index.d.ts",
+            "default": "./framework/*/index.js"
+        },
+        "./framework/*/index.js": {
+            "types": "./framework/*/index.d.ts",
+            "default": "./framework/*/index.js"
+        },
+        "./nextjs": {
+            "types": "./nextjs/index.d.ts",
+            "default": "./nextjs/index.js"
+        },
+        "./nextjs/index": {
+            "types": "./nextjs/index.d.ts",
+            "default": "./nextjs/index.js"
+        },
+        "./nextjs/index.js": {
+            "types": "./nextjs/index.d.ts",
+            "default": "./nextjs/index.js"
+        },
+        "./types": {
+            "types": "./types/index.d.ts",
+            "default": "./types/index.js"
+        },
+        "./types/index": {
+            "types": "./types/index.d.ts",
+            "default": "./types/index.js"
+        },
+        "./types/index.js": {
+            "types": "./types/index.d.ts",
+            "default": "./types/index.js"
+        },
+        "./lib/*": {
+            "types": "./lib/*.d.ts",
+            "default": "./lib/*.js"
+        },
+        "./lib/*.js": {
+            "types": "./lib/*.d.ts",
+            "default": "./lib/*.js"
+        },
+        "./recipe/*": {
+            "types": "./recipe/*/index.d.ts",
+            "default": "./recipe/*/index.js"
+        },
+        "./recipe/*/index": {
+            "types": "./recipe/*/index.d.ts",
+            "default": "./recipe/*/index.js"
+        },
+        "./recipe/*/index.js": {
+            "types": "./recipe/*/index.d.ts",
+            "default": "./recipe/*/index.js"
+        },
+        "./recipe/session/claims": {
+            "types": "./recipe/session/claims.d.ts",
+            "default": "./recipe/session/claims.js"
+        },
+        "./recipe/session/claims.js": {
+            "types": "./recipe/session/claims.d.ts",
+            "default": "./recipe/session/claims.js"
+        }
+    },
     "author": "rishabhpoddar",
     "license": "Apache-2.0",
     "bugs": {

test/testExports.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+
+TEST_PROJECT_DIR=./temp_test_exports
+
+mkdir -p $TEST_PROJECT_DIR
+
+npm pack || exit $?
+
+mv supertokens-node-*.tgz $TEST_PROJECT_DIR
+cd $TEST_PROJECT_DIR
+
+npm init -y || exit $?
+
+rm -f index.mjs
+touch index.mjs
+# We test that all JS files we publish are importable without an extension
+tar -t -f ./supertokens-node* | grep \\.js$ | sed 's/^package\/\(.*\)\.js$/import \"supertokens-node\/\1\";/' >> index.mjs
+# We test that all JS files we publish are importable with the JS extension
+tar -t -f ./supertokens-node* | grep \\.js$ | sed 's/^package\/\(.*\)\.js$/import \"supertokens-node\/\1\.js";/' >> index.mjs
+# We test that all folders that have an index.js (outside of /lib/build) are importable as folders.
+tar -t -f --exclude package/lib/build ./supertokens-node* | grep package/.*/index\\.js$ | sed 's/^package\/\(.*\)\/index\.js$/import \"supertokens-node\/\1\";/' >> index.mjs
+# We also test that the sdk itself is importable
+echo 'import "supertokens-node";' >> index.mjs
+
+mkdir -p node_modules/supertokens-node
+
+tar -xvvf supertokens-node-*.tgz --strip-components=1 -C node_modules/supertokens-node package
+
+node index.mjs
+EXIT_CODE=$?
+
+cd ..
+rm -rf $TEST_PROJECT_DIR
+exit $EXIT_CODE
+