Installation

Looking to integrate Stringtale into your (existing) project? You’ve come to the right place! This guide will lead you through the required steps and get you up and running in minutes.

Before getting started

Introduction of components

Understanding the different components of Stringtale up front will aid your integration. Here’s a run down of the components.

JavaScript libraries (for integration with the front- and back-end of your project)
Command Line Utility (CLI) (for easier integration and local usage)
Dashboard (for creating and managing projects, users as well as billing)
Utilities such as a GitHub action (optional), a Visual Studio Code extension and an ESlint plugin

How does it work once integrated?

Stringtale works as a client side JavaScript library that activates either by either adding ?stringtale to the URL or by enabling it through the Chrome extension. When edited text gets saved, it makes a call to the /api/stringtale route of your back-end, which then passes it on to Stringtale for storage. Your back-end will then in turn call the Stringtale API, authenticating using the Deploy key.

Integrating Stringtale

Integrating Stringtale is easy. All you need to do is add an API route to your backend (which we provide) and expose it to your codebase through the <StringtaleProvider>. After that you can use it anywhere in your code.

Integrating Stringtale on your back-end

The fastest way to get started is to use our CLI for semi-automatic integration. If you prefer to do things manually, please refer to the documentation for your back-end framework. Our automatic integration is suited for both new and existing project. To use the CLI, follow the steps below.

Install the Stringtale CLI globally:

  npm install -g @stringtale/cli

  yarn global add @stringtale/cli

  pnpm install -g @stringtale/cli

Login using with your Stringtale credentials stringtale login
Run stringtale init, and follow the prompts.
1. Select your language (Typescript or JavaScript).
2. Select which Stringtale project should be assigned to this project.
3. Select which back-end framework you use (Next.js or Express.js).
4. The CLI will then generate a stringtale.config.json for your project.
5. Depending on the selected back-end the CLI will perform the following steps:
  1. Attempt to locate your next.config.js to detect the root of your project or prompt you if it can’t find the correct one.
  2. Create app/api/stringtale.ts to enable /api/stringtale.
  3. Add the required dependencies for your project.
  4. Instruct you to add <StringtaleProvider> and Stringtale’s CSS to your RootLayout in app/layout.tsx as such:
    import { StringtaleProvider } from "@stringtale/next" import "@stringtale/react/styles.css" export default async function RootLayout({ children, }: { children: React.ReactNode }) { return ( <html> <body> <StringtaleProvider>{children}</StringtaleProvider> </body> </html> ) }
    For more information about RootLayout see the NextJS documentation.
  1. Attempt to locate your next.config.js to detect the root of your project or prompt you if it can’t find the correct one.
  2. Create <PROJECT_DIRECTORY>/pages/api/stringtale.ts to enable /api/stringtale.
  3. Add the required dependencies for your project.
  4. It will instruct you to customize your App component in _app.tsx and add the <StringtaleProvider>
    import type { AppProps } from 'next/app' import { StringTaleProvider } from "@stringtale/next" import "@stringtale/react/styles.css" export default function MyApp({ Component, pageProps }: AppProps) { return ( <StringtaleProvider> <Component {...pageProps} /> </StringtaleProvider> ) }
    For more information about customizing the App component see the NextJS documentation.
  1. Add the required dependencies for your project.
  2. Instruct you to add the /api/stringtale route. Because of how Express handles routing, we don’t add this automatically. Example:
    import express from 'express' import { setupRoute } from "@stringtale/express" const app = express() app.all('/api/stringtale', setupRoute({ apiKey: process.env.STRINGTALE_API_KEY! }))
  3. Instruct you to add the <StringtaleProvider> with apiRoute attribute to App component in app.js / app.tsx. Example:
    import { StringtaleProvider } from "@stringtale/react" import "@stringtale/react/styles.css" function App() { return ( <StringtaleProvider apiRoute="https://www.example.com/api/stringtale"> <div className="App" /> </StringtaleProvider> ) } export default App
Once stringtale init has finished, it’s integrated with your back-end. To start using Stringtale in your front-end, check out the next section.

Integrating Stringtale on your front-end

In order to integrate Stringtale in your React front-end you can either start wrapping your strings manually, or make use of our Codemod.

Automated wrapping using Codemod

You can wrap all the static text in your sourcecode using our Codemod utility. By running stringtale codemod our CLI will automatically wrap all the static text in your codebase in <Value> tags and generate name attributes for them.

Manual wrapping

To start using Stringtale on a subset of your strings, please refer to the documentation for the React framework.

Deploying Stringtale to your test environment

Deploying Stringtale to your test environment is very straight forward. Just deploy your application as usual, add STRINGTALE_API_KEY to your environment variables and you’re good to go. To obtain the STRINGTALE_API_KEY you can follow the steps below:

Go to the Stringtale Dashboard.
Go to Projects
Open the project (or click on Edit project settings) you want to deploy to your test / preview environment.
Scroll down to Tokens
Click on Add Token and create a new token

Save the token somewhere safe, you’ll need it later.

Enable ‘Write’ permissions for the newly created token by checking the checkbox for ‘Can write’.

Now you can deploy your application and add STRINGTALE_API_KEY to your environment variables. You can start using Stringtale by adding ?stringtale to the URL or by using our browser extension.

For more information on how to use Stringtale once you’ve deployed it, checkout the workflow documentation.