Skip to main content

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.


  • No switch statements, use if, else instead.

  • Camel case is preferred over using underscores.

  • Classes must start with a capital letter, but variables with a small letter

  • Do not create excessive interfaces / abstract classes. Ask yourself - if I don't create an abstraction, what would be the downside? If the answer to that is not clear, don't do it.

  • Miscellaneous functions like checkEmailFormat, or convertToBase64() can go into a class. No need to create separate files for them.

  • Use @Nullable, @Nonnull as much as possible. We know that using Optional<> is a better idea, but that was not used from the start. Perhaps we can switch to that since that is far better than relying on annotations.

  • Use @deprecated to deprecate functions and classes. When using this, make sure to use it in all functions that use the deprecated function as well (if applicable). If a user facing function needs to be deprecated, make sure to check that that's happening by using the playground.

  • If a function is only meant to be used during testing, use @TestOnly annotation.

  • About exceptions:

    • Refrain from using throws Exception. Create specific exception types whenever possible.
    • Custom exceptions must not be of type RuntimeException as far as possible. This is because the compiler will not tell you about them.
    • When expecting to handle exceptions in special way (for example return a non OK status from an API as opposed to 500 status code), always create a custom java exception class for that. This is because if we use an inbuilt exception class, then there could be other functions which throw that error which might lead to returning the non OK status from an API unintentionally.
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI