diff --git a/.eslintrc b/.eslintrc
index dd819129f9..d0f3978f40 100644
--- a/.eslintrc
+++ b/.eslintrc
@@ -7,11 +7,13 @@
"node_modules/",
"dist/",
"**sample-app**/",
- "**playground**/"
+ "**playground**/",
+ "*.cjs",
+ "tests/func-tests/"
],
"parser": "@typescript-eslint/parser",
"parserOptions": {
- "project": "./tsconfig.json",
+ "project": "./tsconfig.base.json",
"tsconfigRootDir": "."
},
"rules": {
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 5a182ef106..5571608bdd 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,4 +1,7 @@
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
+# prevent heap limit allocation errors
+export NODE_OPTIONS="--max-old-space-size=4096"
+
yarn lint-staged
diff --git a/build-dependents.js b/build-dependents.js
index fb53b404a1..d0cf7cade7 100755
--- a/build-dependents.js
+++ b/build-dependents.js
@@ -23,7 +23,7 @@ try {
if (isDependent || changedProject === currentProject) {
// Rebuild the current project
- const command = `nx run-many --target=d --projects=${currentProject} --parallel=5`;
+ const command = `nx run-many --target=d --projects=${currentProject} --parallel=5 --no-cloud`;
console.log(`Running command: ${command}`);
execSync(command, { stdio: 'inherit' });
diff --git a/dev.sh b/dev.sh
index 44ad4a48d0..19f7726e37 100755
--- a/dev.sh
+++ b/dev.sh
@@ -28,5 +28,5 @@ fi
# Run nx commands with the selected or provided package name
echo "Running commands for package: $PACKAGE_NAME"
-nx run $PACKAGE_NAME:d --parallel=5
+nx run $PACKAGE_NAME:d --parallel=5 --no-cloud
nx watch --all -- node ./build-dependents.js \$NX_PROJECT_NAME $(echo $PACKAGE_NAME)
\ No newline at end of file
diff --git a/examples/README.md b/examples/README.md
index f7d57ec1b4..139facd03b 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,15 +1,75 @@
-## Contribution Guidelines
+
+
+
+
-Important information on how to create examples, pull them through to the docs site and ensure they are covered by tests in the CI CD pipeline.
+
Immutable Code Examples
+
+ Immutable's code examples as used for the code snippets in the Immutable Docs
+
+ Explore the docs »
+
+
+
+
-## Example Scope
+**Table of Contents**
-When creating an example app it should contain only examples about one particular feature to prevent overloading the example. If there are multiple ways to use the feature then it is okay to include those in one sample app.
+- [Introduction](#introduction)
+- [Running examples locally](#running-examples-locally)
+- [Contribution guidelines](#contribution-guidelines)
+- [Adding examples](#adding-examples)
+- [End to end testing](#end-to-end-testing)
+- [Using code examples in the docs site](#using-code-examples-in-the-docs-site)
+
-For example;
+# Introduction
-the app in `examples/passport/wallets-connect-with-nextjs` show how to connect passport in the nextjs framework. It contains a default route that has links to each of the examples. Inside there are three routes, one for each way to connect (EIP-1193, EtherJS and Wagmi). These are okay to be part of one sample app since they show how to use one feature but using 3 different libraries.
+The example apps in this examples directory are compiled and tested as part of our CI CD pipeline. The goal of this is to ensure the examples found here are always able to run against the latest version of the Immutable Typescript SDK.
+
+Selected portions of code from these example apps are then displayed as code snippets in our docs site, which means our code snippets in the docs are inherently always accurate as well. How to include the code from here in the docs site is explained below.
+
+These example apps can also be used directly as a reference and run locally to test and develop with.
+
+# Running examples locally
+
+First you need to clone or fork the `ts-immutable-sdk` repo. The examples are a part of the root workspace and running yarn install from anywhere in the workspace will install the node modules required by the examples to the root `node_modules` directory. By default, the examples pull the latest sdk version from NPM instead of building the SDK locally.
+
+If you want to run the examples against your local build of the SDK instead, from the project root run;
+
+```bash
+yarn prepare:examples
+```
+
+and it will build the SDK first then use that build instead of what is on NPM. This is what our CI CD pipeline does to ensure it's compiling and testing the examples against the latest changes rather than what's already on NPM.
+
+Take a look at the README.md file of the example you want to run e.g. the [Passport Connect Readme](/examples/passport/wallets-connect-with-nextjs/README.md)
+
+This should include the steps required to run the example. Generally you will need to;
+
+1. Copy the `.env.example` file to `.env` and populate it with the environment variables as per the readme.
+1. Then `yarn install` and `yarn dev`
+
+And the app should be served on https://localhost:3000 unless otherwise stated in the example app.
+
+# Contribution guidelines
+
+This section explains some of the core concepts for how we want to structure the examples so they can be more easily digested in the docs and by our partners.
+
+The goal is to have easy to read, well commented examples that focus on showing how to use a singular feature without being overly long or complicated. They should not include overly opinionated framework implementations as it can make it unclear to the reader what is required and what is optional. They should be compilable and tested with e2e tests as much as is practical.
+
+In the long run we want these apps to run in a code blitz frame inside the docs site much like on the [Checkout Connect Widget](https://docs.immutable.com/products/zkEVM/checkout/widgets/connect#sample-code) docs page. So aim to create an example which can be runnable like this.
+
+We also want to eventually index these examples and serve them in a searchable and filterable page on the docs site, so feel free to add more examples here which are not necessarily used as code snippets in the docs site.
+
+## Examples scope
+
+When creating an example app it should contain only examples about one particular feature to prevent overloading the example. If there are multiple ways to use the feature then it is okay to include those in one example app.
+
+For example, the [Passport Connect with NextJS](/examples/passport/wallets-connect-with-nextjs) app shows how to connect passport in the NextJS framework.
+
+It contains a default route that has links to each of the examples. Inside there are three routes, one for each way to connect (EIP-1193, EtherJS and Wagmi). These are okay to be part of one example app since they show how to use one feature but using 3 different libraries.
If you want to show a different feature e.g signing with passport, you should create a new example app. Even though it also requires passport to connect you should not add the signing example to the connect example app.
@@ -44,20 +104,57 @@ examples
│ └── ...
```
-If you need to create a new example follow the steps below;
+# Adding examples
-## Creating a New Example
+Depending on the scope of the example you're trying to add, you may be able to add it to an existing example app, or you might have to create a new example app. If you're not sure, read the [Examples Scope](#examples-scope) section above to help you decide.
-create the nextjs project
+If you need to add a new example or add to an existing example, please follow the [Folder Structure](#folder-structure) guidelines above.
-```
+## Add to an existing example app
+
+The process may differ depending on how the example app is setup, but the recommendations we have made around creating a new example should follow the same structure as we've implemented for the [[Passport Connect with NextJS](/examples/passport/wallets-connect-with-nextjs) and [Passport Signing with NextJS](/examples/passport/wallets-signing-with-nextjs) examples.
+
+So if you need to add a new example to an existing example app you should create a branch in `ts-immutable-sdk` to add your example to and follow these steps;
+
+### Setup example in existing app
+
+1. Create new route folder inside the example app and add the `page.tsx` file.
+1. Add the new route you created to the app's home page
+1. Add any packages you require
+1. Add any environment variables your example requires to the `.env.example` file
+1. Add instructions in the `README.md` file about how to populate the `.env` file and any other build instructions.
+
+### Add your example
+
+Once you've done this you can go ahead and write your example code in the `page.tsx` file.
+
+You can run the example locally to test your code by following the steps in the [Running examples locally](#running-examples-locally) section.
+
+You will also need to create e2e tests for your example as covered in the [End to end testing](#end-to-end-testing) section.
+
+Creating code snippets in the docs site using your example code is covered in the [Using code examples in the docs site](#using-code-examples-in-the-docs-site) section.
+
+If your code example is going to be used as code snippets in the docs site, before merging your branch to main in `ts-immutable-sdk` you should follow the steps in [Using code examples in the docs site](#using-code-examples-in-the-docs-site). These steps help you to test the code snippets in the docs site before you merge your PR which avoids double handling and multiple pull requests across both repos.
+
+## Creating a new example app
+
+The process may differ if you're using a different Javascript Framework, but this assumes you will be creating a new example app using NextJS. These steps which were implemented to create the [Passport Connect](/examples/passport/wallets-connect-with-nextjs) example. It is a good reference point in terms of route structure and page layouts. If you need to copy code from there to help with your layouts then please go ahead.
+
+### Setup example app
+
+If you want to make a new NextJS app from scratch this is the process;
+
+Create a branch in `ts-immutable-sdk` to add your example to.
+
+In the console navigate to the product directory where your example will live (or create one if it doesn't exist). Then use `yarn dlx` to create the app.
+```bash
cd examples/
yarn dlx create-next-app@latest
```
-use the default options
-```
-✔ What is your project named? -with- e.g. wallets-with-nextjs
+use the default options;
+```bash
+✔ What is your project named? @examples//-with- e.g. @examples/passport/connect-with-nextjs
✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
@@ -66,162 +163,85 @@ use the default options
✔ Would you like to customize the default import alias (@/*)? No
```
-install dependencies
+Install `@imtbl/sdk` and any other dependencies your example needs e.g.
-```
-yarn install
-```
-
-install `@imtbl/sdk` and any other dependencies your example needs e.g.
-
-```
+```bash
yarn add @imtbl/sdk
yarn add @ethersproject/providers@^5.7.2
```
-create a `.env.example` file in the root of the example. This will be committed to git so don't fill in the values
+Create a `.env.example` file in the root of the example. This will be committed to git so don't fill in the values
-add a template for any environment variables you need to the `.env.example` file e.g.
+Add a template for any environment variables you need to the `.env.example` file e.g.
-```
+```js
NEXT_PUBLIC_PUBLISHABLE_KEY=
NEXT_PUBLIC_CLIENT_ID=
```
-copy the `.env.example` file to `.env` in the root of the example. The `.env` file should be automatically ignored by git.
-
-populate any API keys and secrets e.g.
-
-```
-NEXT_PUBLIC_PUBLISHABLE_KEY="ABC"
-NEXT_PUBLIC_CLIENT_ID="XYZ"
-```
+Copy the `.env.example` file to `.env` in the root of the example (the `.env` file should be automatically ignored by git). Then populate any API keys and secrets you need to use in your application into the `.env` file.
-note: variables must be prefixed with `NEXT_PUBLIC_` to be piped into the browser env.
+Note: variables must be prefixed with `NEXT_PUBLIC_` to be piped into the browser env.
-Update the readme with any instructions required to run the app, and include what required env variables there are with any instructions on what to populate there.
+Update the readme with any instructions required to run the app, and include what required env variables there are with any instructions on what to populate there e.g.
-```
+```md
## Required Environment Variables
- NEXT_PUBLIC_PUBLISHABLE_KEY // replace with your publishable API key from Hub
- NEXT_PUBLIC_CLIENT_ID // replace with your client ID from Hub
```
-start the project with hot reloading
+Delete the any unused imports in `app/page.tsx`
-```
-yarn dev
-```
+Delete the contents of the return statement in `app/page.tsx` and replace with `