Skip to content

feat: adds contributing docs #1003

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

feat: adds contributing docs #1003

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76eaaa2
feat: adds Python contributing docs
namsnath Jul 7, 2025
eddc0f2
update: move to references tab, update docs
namsnath Jul 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/references/contribute/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"label": "Contribute",
"customProps": {
"isMainCategory": true
},
"position": 11
}
12 changes: 12 additions & 0 deletions docs/references/contribute/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
title: Introduction
hide_title: true
hide_table_of_contents: true
sidebar_position: 1
description: Contribute to SuperTokens
page_type: sdk-reference
category: contribute
---

# Introduction

126 changes: 126 additions & 0 deletions docs/references/contribute/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
---
title: Development Setup
hide_title: true
hide_table_of_contents: true
sidebar_position: 2
description: Setting up repositories for local development
page_type: sdk-reference
category: contribute
---

# Development Setup

Check warning on line 11 in docs/references/contribute/setup.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.headings] 'Development Setup' should use sentence-style capitalization.

Raw Output:
{"message": "[SuperTokens.headings] 'Development Setup' should use sentence-style capitalization.", "location": {"path": "docs/references/contribute/setup.mdx", "range": {"start": {"line": 11, "column": 3}}}, "severity": "WARNING"}

## Prerequisites
<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

- NodeJS (20 or above) and `npm`
- Any IDE
- [VSCode](https://code.visualstudio.com)
- Any equivalent IDE

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

- Python (3.8 or above)
- Any IDE
- [PyCharm](https://www.jetbrains.com/pycharm/download) (recommended)
- [VSCode](https://code.visualstudio.com)
- Any equivalent IDE

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-core">

- Java 21.0.7

</RepositoryTabs.TabItem>

</RepositoryTabs>

## Setup
<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

- Fork the [supertokens-node](https://github.com/supertokens/supertokens-node) repository
- Clone the forked repository
- Install dependencies: `npm i -d`
- Enable pre-commit hooks: `npm run set-up-hooks`

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

- Fork the [supertokens-python](https://github.com/supertokens/supertokens-python) repository
- Clone the forked repository
- Create a virtual environment for the project and activate it
- Install dependencies: `make dev-install`
- Enable pre-commit hooks: `make set-up-hooks`

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-core">

- Fork the [supertokens-core](https://github.com/supertokens/supertokens-core) repository
- Clone the [supertokens-root](https://github.com/supertokens/supertokens-root) repository in the same parent directory
```
- parent_directory
- supertokens-core
- supertokens-root
```
- Navigate to the `supertoken-root` repository
- Open the `modules.txt` file in an editor
- The modules.txt file contains the core, plugin-interface, the type of plugin and their branches(versions)
- By default the `master` branch is used but you can change the branch depending on which version you want to modify
- The `sqlite-plugin` is used as the default plugin as it is an in-memory database and requires no setup
- [core](https://github.com/supertokens/supertokens-core)
- [plugin-interface](https://github.com/supertokens/supertokens-plugin-interface)
- Check the repository branches by clicking on the links listed above, click the branch tab and check for all the available versions
- Add your github username separated by a ',' after core,master in modules.txt
- If, for example, your github `username` is `helloworld` then modules.txt should look like
```
// put module name like module name,branch name,github username(if contributing with a forked repository) and then call ./loadModules script
core,master,helloworld
plugin-interface,master
sqlite-plugin,master
```
- Run `./loadModules` to clone the required repositories

### Running the core locally
- Run `startTestEnv --wait` in a terminal and keep it running
- Navigate to `supertokens-root` in a new terminal and run `cp ./temp/config.yaml .`
- Run `java -classpath "./core/*:./plugin-interface/*:./ee/*" io.supertokens.Main ./ DEV`
- This will start the core, listening on `http://localhost:3567`

</RepositoryTabs.TabItem>

</RepositoryTabs>

## Modifying Code

Check warning on line 102 in docs/references/contribute/setup.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.headings] 'Modifying Code' should use sentence-style capitalization.

Raw Output:
{"message": "[SuperTokens.headings] 'Modifying Code' should use sentence-style capitalization.", "location": {"path": "docs/references/contribute/setup.mdx", "range": {"start": {"line": 102, "column": 4}}}, "severity": "WARNING"}
<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

- Open the `supertokens-node` project in your IDE to start modifying code
- Run `npm run build-pretty` to build the project and find/fix lint/formatting errors before committing

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

- Open the `supertokens-python` project in your IDE to start modifying code
- Run `make lint` to find/fix lint/formatting errors before committing

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-core">

- Open the `supertokens-core` project in your IDE to start modifying code
- After gradle has imported all the dependencies, you can start modifying the code

</RepositoryTabs.TabItem>

</RepositoryTabs>
249 changes: 249 additions & 0 deletions docs/references/contribute/testing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,249 @@
---
title: Testing
hide_title: true
hide_table_of_contents: true
sidebar_position: 3
description: Testing changes
page_type: sdk-reference
category: contribute
---

# Testing

## Prerequisites

- Install `docker`
- [Docker Desktop](https://docs.docker.com/desktop/) is convenient to install and use, and includes a Docker Engine.
- [Docker Engine](https://docs.docker.com/engine/install/) is the minimum requirement to spin up containers required for tests.

<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

1. Setup repositories for integration/end-to-end testing
1. [supertokens-auth-react](https://github.com/supertokens/supertokens-auth-react)
2. [backend-sdk-testing](https://github.com/supertokens/backend-sdk-testing)

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

1. Setup repositories for integration/end-to-end testing
1. [supertokens-auth-react](https://github.com/supertokens/supertokens-auth-react)
2. [backend-sdk-testing](https://github.com/supertokens/backend-sdk-testing)

</RepositoryTabs.TabItem>

</RepositoryTabs>

## Unit Tests

Check warning on line 39 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.headings] 'Unit Tests' should use sentence-style capitalization.

Raw Output:
{"message": "[SuperTokens.headings] 'Unit Tests' should use sentence-style capitalization.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 39, "column": 4}}}, "severity": "WARNING"}
<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

1. Run `docker compose up --wait` to start up the required containers
2. Run `npm run test`

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

### Run all tests
1. Run `make test`
1. Note: This starts up and tears down docker containers required for the tests to run
2. Defaults to using the latest `supertokens-core` image
1. Set the `SUPERTOKENS_CORE_VERSION` environment to pull a different image

### Run individual tests
1. Run `docker compose up --wait` to start up the required containers
2. Run tests
1. `pytest tests/<path_to_file>` to run a single file
2. `pytest tests/<path_to_file>::<test_function>` to run a single test

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-core">

### Testing Locally

1. Navigate to the `supertokens-root` repository
2. Run all tests: `.startTestEnv`

### Using Github Actions

1. Navigate to your `supertokens-core` fork on GitHub
2. Navigate to the `Actions` tab
3. Find the action named `Run Tests` and navigate to it
4. Click on the `Run workflow` button
5. Set the variables
1. `supertokens-plugin-interface owner name` - If `supertokens-plugin-interface` was forked, input your GitHub username
2. `supertokens-plugin-interface branch name` - If the core version you are working on is compatible with a plugin-interface version that is not on the master branch, set this to the appropriate branch
6. Click on the `Run workflow` button

</RepositoryTabs.TabItem>

</RepositoryTabs>


## Backend SDK Testing

Check warning on line 88 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.headings] 'Backend SDK Testing' should use sentence-style capitalization.

Raw Output:
{"message": "[SuperTokens.headings] 'Backend SDK Testing' should use sentence-style capitalization.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 88, "column": 4}}}, "severity": "WARNING"}
Integration tests to test backend SDK functionality.

1. Start docker containers
1. `docker compose up --wait`
2. Set environment variables
1. `export SUPERTOKENS_ENV=testing`
2. `export TEST_MODE=testing`
3. `export API_PORT=3030`

<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

3. Start the application server:
1. Navigate to `supertokens-node/test/test-server`
2. `node .`

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

3. Start the application server:
1. Navigate to `supertokens-python/test/test-server`
2. `python app.py`

</RepositoryTabs.TabItem>

4. Run `backend-sdk-testing` tests
1. Navigate to `backend-sdk-testing`
2. `npm install`
3. `npm run build`
4. `npm test`

</RepositoryTabs>

## Auth-React Tests

Check warning on line 124 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.headings] 'Auth-React Tests' should use sentence-style capitalization.

Raw Output:
{"message": "[SuperTokens.headings] 'Auth-React Tests' should use sentence-style capitalization.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 124, "column": 4}}}, "severity": "WARNING"}
End-to-end tests using `supertokens-auth-react` as the frontend.

Check warning on line 125 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.

Raw Output:
{"message": "[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 125, "column": 25}}}, "severity": "WARNING"}

1. Start docker containers
1. `docker compose up --wait`
2. Set environment variables
1. `export SUPERTOKENS_ENV=testing`
2. `export TEST_MODE=testing`
3. `export APP_SERVER=8083`
4. `export NODE_PORT=8082`
5. `export PORT=3031`

Check warning on line 134 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.acronyms] 'PORT' has no definition.

Raw Output:
{"message": "[SuperTokens.acronyms] 'PORT' has no definition.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 134, "column": 20}}}, "severity": "INFO"}
6. `export REACT_APP_API_PORT=8083`

<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

3. Startthe application server:
1. Navigate to `supertokens-node/test/auth-react-server`
2. `npm install`
3. `NODE_PORT=8083 node .`

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

3. Start the application server:
1. Django
1. Navigate to `supertokens-python/tests/auth-react/django3x`
2. `uvicorn mysite.asgi:application --port 8083`
2. FastAPI
1. Navigate to `supertokens-python/tests/auth-react/fastapi-server`
2. `uvicorn app:app --host 0.0.0.0 --port 8083`
3. Flask
1. Navigate to `supertokens-python/tests/auth-react/flask-server`
2. `python3 app.py --port 8083`

</RepositoryTabs.TabItem>

</RepositoryTabs>


4. Setup `supertokens-auth-react`
1. Navigate to `supertokens-auth-react`

Check warning on line 167 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.

Raw Output:
{"message": "[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 167, "column": 25}}}, "severity": "WARNING"}
2. `npm install`
5. Run `supertokens-auth-react` tests
1. Navigate to `supertokens-auth-react/test/server` in a new terminal

Check warning on line 170 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.

Raw Output:
{"message": "[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 170, "column": 25}}}, "severity": "WARNING"}
2. `npm install`
3. `node .`
3. Navigate to `supertokens-auth-react/examples/for-tests` in a new terminal

Check warning on line 173 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.

Raw Output:
{"message": "[SuperTokens.words] Use '**SuperTokens**' instead of 'supertokens'.", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 173, "column": 25}}}, "severity": "WARNING"}
4. `npm install`
6. `npm start`
6. Wait a few seconds for the frontend application to start
7. Run tests
1. ALl tests: `npx mocha`

Check failure on line 178 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.spelling] This word is not recognized: 'npx'

Raw Output:
{"message": "[SuperTokens.spelling] This word is not recognized: 'npx'", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 178, "column": 28}}}, "severity": "ERROR"}
2. Specific specs: `npx mocha --spec <path_to_spec>`

Check failure on line 179 in docs/references/contribute/testing.mdx

View workflow job for this annotation

GitHub Actions / vale-lint 

[vale] reported by reviewdog 🐶
[SuperTokens.spelling] This word is not recognized: 'npx'

Raw Output:
{"message": "[SuperTokens.spelling] This word is not recognized: 'npx'", "location": {"path": "docs/references/contribute/testing.mdx", "range": {"start": {"line": 179, "column": 33}}}, "severity": "ERROR"}


## Website Tests
End-to-end tests using `supertokens-website` as the frontend.

1. Start docker containers
1. `docker compose up --wait`
2. Set environment variables
1. `export SUPERTOKENS_ENV=testing`
2. `export TEST_MODE=testing`

<RepositoryTabs>

<RepositoryTabs.TabItem value="supertokens-node">

3. Start the application and cross-domain servers:
1. Navigate to `supertokens-node/test/frontendIntegration` in two new terminals
2. `npm install`
3. `NODE_PORT=8080 node .` in terminal 1
4. `NODE_PORT=8082 node .` in terminal 2

</RepositoryTabs.TabItem>

<RepositoryTabs.TabItem value="supertokens-python">

3. Start the application and cross-domain servers:
1. Django2
1. Navigate to `supertokens-python/tests/frontendIntegration/django2x` in two new terminals
2. `make with-django2x`
3. `gunicorn mysite.wsgi --bind 0.0.0.0:8080` in terminal 1
4. `gunicorn mysite.wsgi --bind 0.0.0.0:8082` in terminal 2
2. Django3
1. Navigate to `supertokens-python/tests/frontendIntegration/django3x` in two new terminals
2. `make with-django`
3. `uvicorn mysite.asgi:application --port 8080` in terminal 1
4. `uvicorn mysite.asgi:application --port 8082` in terminal 2
3. DRF Sync
1. Navigate to `supertokens-python/tests/frontendIntegration/drf_sync` in two new terminals
2. `make with-drf`
3. `gunicorn mysite.wsgi --bind 0.0.0.0:8080` in terminal 1
4. `gunicorn mysite.wsgi --bind 0.0.0.0:8082` in terminal 2
4. DRF Async
1. Navigate to `supertokens-python/tests/frontendIntegration/drf_async` in two new terminals
2. `make with-drf`
3. `uvicorn mysite.asgi:application --port 8080` in terminal 1
4. `uvicorn mysite.asgi:application --port 8082` in terminal 2
5. FastAPI
1. Navigate to `supertokens-python/tests/frontendIntegration/fastapi-server` in two new terminals
2. `make with-fastapi`
3. `uvicorn app:app --host 0.0.0.0 --port 8080` in terminal 1
4. `uvicorn app:app --host 0.0.0.0 --port 8082` in terminal 2
6. Flask
1. Navigate to `supertokens-python/tests/frontendIntegration/flask-server` in two new terminals
2. `make with-flask`
3. `python3 app.py --port 8080` in terminal 1
4. `python3 app.py --port 8082` in terminal 2

</RepositoryTabs.TabItem>

</RepositoryTabs>

4. Setup `supertokens-website`
1. Navigate to `supertokens-website`
2. `npm install`
5. Run `supertokens-website` tests
1. Navigate to `supertokens-website/test/server` in a new terminal
2. `npm install`
3. `NODE_PORT=8081 node .`
3. Navigate to `supertokens-website/` in a new terminal
7. Run tests: `npm test`
Loading
Loading