Installation

Looking to integrate Stringtale into an existing or new project? This guide walks you through the required steps for the back-end and front-end integration.

Before getting started

Introduction of components

Understanding the different components of Stringtale up front will aid your integration. Here’s a rundown 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 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 authenticates with the Stringtale API using your API key (STRINGTALE_API_KEY).

Stringtale requires a back-end server (currently Next.js or Express.js) to handle that communication. The React front-end library alone is not enough.

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 projects. 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

Log in 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/route.ts (or under src/app/...) 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:
    
    To enable additional Stringtale features, check out the StringtaleProvider documentation.
    
    import { StringtaleProvider } from "@stringtale/react" 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 Next.js 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 pages/api/stringtale.ts (or under src/pages/...) to enable /api/stringtale.
  3. Add the required dependencies for your project.
  4. Instruct you to customize your App component in _app.tsx and add the <StringtaleProvider>:
    
    To enable additional Stringtale features, check out the StringtaleProvider documentation.
    
    import type { AppProps } from 'next/app' import { StringtaleProvider } from "@stringtale/react" 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 Next.js 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:
    
    To enable additional Stringtale features, check out the StringtaleProvider documentation.
    
    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 source code 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 straightforward. Deploy your application as usual, add STRINGTALE_API_KEY to your environment variables and you’re good to go.

Create an API key in the Stringtale Dashboard with write permissions.
Deploy your application and set STRINGTALE_API_KEY to that key in your test / preview environment.
Activate 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, check out the workflow documentation.