Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


🗣 Easy text-to-speech for your Gatsby site, powered by Amazon Polly.


Pull requests are welcome! npm GitHub license


npm install --save gatsby-transformer-polly

How to use


  1. In order to use this plugin you need an AWS account. You can use the text-to-speech service (AWS Polly) for free for the first 12 months (up to a couple million words to be precise).

    Attention: If you exceed the limits or use it after your initial free tier, using this plugin will generate costs in your AWS account!

  2. As this plugin is based on SSML files, the gatsby-source-filesystem is required to be installed and configured as well.

Mandatory configurations


To include this plugin add it to your gatsby-config.js file as follows. Also, make sure you have included an entry for the necessary gatsby-source-filesystem plugin. Now link them together by setting gatsby-transformer-polly’s ssmlFilesSourceInstanceName option to the same value as gatsby-source-filesystem’s name option.

The other options shown in this example are also mandatory:

// In your gatsby-config.js
plugins: [
    resolve: `gatsby-source-filesystem`,
    options: {
      name: `ssml`,
      path: `${__dirname}/src/ssml/`,
    resolve: `gatsby-transformer-polly`,
    options: {
      ssmlFilesSourceInstanceName: `ssml`,
      awsRegion: `us-east-1`,

AWS credentials

The plugin requires your AWS credentials in order to generate the text-to-speech data.

Important: For security reasons it is not a good idea to keep access keys with administrator permissions on your local machine, without at least using MFA authentication. Even better is to restrict the AWS user’s permissions to AmazonPollyReadOnlyAccess, which is all this plugin needs.

There are various ways to provide your AWS credentials to the plugin. For example:

  • Create a shared credentials file and add a profile for your AWS user that will use AWS Polly. You can either configure it as your default profile or use the awsProfile plugin option or AWS_PROFILE environment variable to pass the custom profile name to the plugin.
// In your gatsby-config.js
    resolve: "gatsby-transformer-polly",
    options: {
      awsProfile: "gatsby-transformer-polly",
  • Use environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to directly configure your user’s access key (e.g. to build in a CI environment).

All configurations

Option Required Example
ssmlFilesSourceInstanceName Yes "ssml"
awsRegion Yes "us-east-1"
awsProfile No "gatsby-transformer-polly"

Create SSML files

As this plugin transforms SSML files into e.g. *.mp3 files or speech mark data, you will have to create some SSML files first.

Create them in the directory defined in the gatsby-source-filesystem declaration inside your gatsby-config.js.

Make sure you only use the SSML tags supported by AWS Polly.

Here is an example SSML file content:

     Hello <break time="300ms"/> World.

Query speech output data

Now you can just query the required data using GraphQL:

const data = useStaticQuery(graphql`
  query {
    file(relativePath: { eq: "hello-world.xml" }) {
      childPolly {
        # Specify the speech output attributes right in the query.
        polly(voiceId: "Justin", audioFileFormat: "mp3") {

Query parameters

The following query parameters can be used to modify the generated speech output:

Parameter Required Example Valid values
voiceId Yes "Justin" See Voices in Amazon Polly
audioFileFormat Yes "mp3" mp3 / ogg_vorbis / pcm
engine No "standard" standard / neural
languageCode No "en-US" See “LanguageCode” in SynthesizeSpeech docs
lexiconNames No ["LexA", "LexB"] See “LexiconNames” in SynthesizeSpeech docs
sampleRate No 16000 See “SampleRate” in SynthesizeSpeech docs
speechMarkTypes No ["sentence", "word"] See “SpeechMarkTypes” in SynthesizeSpeech docs

Contribute 🦸

Contributions are more than welcome! I would love to see text-to-speech becoming a thing in the already very accessible Gatsby ecosystem. If you agree with this and would like to join me on this mission it would be awesome to get in touch! 😊

Please feel free to create, comment and of course solve some of the issues. To get started you can also go for the easier issues marked with the good first issue label if you like.


The MIT License


The gatsby-transformer-polly library is maintained and sponsored by the Swiss web and mobile app development company Florian Gyger Software.

If this library saved you some time and money please consider sponsoring me, so I can build more libraries for free and actively maintain them for you. Thank you 🙏

© 2023 Gatsby, Inc.