GraphQL

GraphQL Contributor Days | December 2021

Published Dec 21, 2021

Updated Feb 13, 2023

6 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

This is a recap of the December GraphQL Contributor Days, an event where maintainers and contributors came together to talk about all things current and upcoming in the GraphQL realm! Read on or rewatch the event here to see what these experts have to share, and see what they're using at companies such as Facebook, PayPal, Hasura, and Netflix.

Our hosts for this event were Dustin Goodman and Tanmai Gopal.

Panelists

Adhithi Ravichandran, @AdhithiRavi
Conor Hastings @stillconor
Jamie Barton, @notrab
Joey Nenni, @JoeyNenni
Jon Wong, @jnwng
Lee Byron, @leeb
Marc-André Giroux, @__xuorig__
Roy Derks, @gethackteam
Tejas Kumar, @TejasKumar_
Uri Goldshtein, @UriGoldshtein
Kyle Schrade, @NotKyleSchrade
Patrick Arminio, @patrick91
Gabriel Nordeborn, @___zth___

Community Showcase & Updates

GraphQL Yoga (Uri Goldshtein)

GraphQL Yoga 2.0 has been in the works for the past few months, and it’s finally launched its alpha! This version is shipping with Envelop, and includes support for deferring streams, live queries, and the latest GraphiQL IDE.

RescriptRelay CLI (Gabriel Nordeborn)

A new feature has been added to the RescriptRelay CLI! This new command has the ability to go through your code and remove all unused fields and fragments from your GraphQL queries, which in turn helps prevent over-fetching in your application.

yarn rescript-relay-cli remove-unused-fields

GraphQL Learning

What can we do to support or easily onboard team members that may be new to GraphQL? What challenges do we face? Our panelists shared some of their favorite resources and methods that have worked for their teams, as well as brought up some great points about resources the community is still lacking.

The general consensus was that folks coming from REST can have trouble learning the GraphQL way of doing things. Things like introspection & HTTP 200 blanket responses can cause errors and introduce security risks that may be overlooked by those learning GraphQL for the first time.

Our panelists also agreed that there’s a need for concise resources outlining some of these common pitfalls, and there’s also a need for a simple, language-agnostic GraphQL starter package (think Create React App, but for GraphQL). Unfortunately, these resources don’t seem to exist just yet. However, our panelists did still have some great tips and resources to share for those trying to learn GraphQL.

Kyle Schrade had a couple suggestions that worked for his team:
- Create internal documentation where you can keep track of answers to common questions.
- Create a Codegen so that it’s easier for new team members to set up subgraphs.
Adhithi Rhavichandran shared a great Pluralsight course she co-authored on GraphQL API’s with Apollo. This is a great language-agnostic intro to GraphQL that talks about the differences between GraphQL and REST.
Jamie Barton created graphql.wtf to provide the GraphQL community with short, digestible videos on GraphQL concepts.

Authorization & Security

How can we handle authorization and security for our GraphQL API’s? What kinds of considerations need to be made? There is no “one size fits all” in handling authorization in GraphQL API’s.

With regards to where one should place their authorization logic, some argued for placing this logic at the resolver level (keeping auth logic close to business logic), while others wished to raise this logic up to a top layer to keep responsibilities separate. If the latter is your preference, Uri Goldshtein recommended GraphQL Authz for easily adding an authorization layer to your GraphQL API. This library is compatible with all modern GraphQL architectures as well.

As mentioned earlier, there were some differing ideas around whether or not to allow schema introspection. Though some saw it as a potential security risk, Joey Nenni argued that the benefits for developers can be enormous and provide a better user experience. If you've properly secured your API, there shouldn't be any significant risks involved with allowing schema introspection.

Federation

What are the benefits and challenges of federating? A pain point for Roy Derks is that underlying services need to be ready for federation. "It'd be nice if every schema could be federated with any schema," he said. Tanmai Gopal suggested that it'd be best to do configuration at the GraphQL entry point, rather than at the service level in order to tackle that problem.

What companies use federation, and how are they implementing it? Many of our panelists' companies are either actively using or planning to use Apollo Federation.

Tanmai Gopal, founder of Hasura, said that Hasura does federation in two steps - service to service federation, and data source to data source federation. At PayPal, Staff Engineer Joey Nenni shared that they're currently working on implementing the Apollo Federation spec.

Marc-André Giroux also shared that Netflix uses the Apollo Federation spec, though they have their own gateway built in Kotlin. The observability federation brings to their API, and the way federation fits within Netflix's microservice architecture works "beautifully" on his team. However, federating a monolith is perhaps not the best idea.

Lee Byron, co-creator of GraphQL, agreed and shared that Facebook has a different approach. "I think federation brings a lot of value, but at a lot of cost," he explained. Schema registries, query plans, and all of the other "stuff" that comes with federation can be a lot to manage.

"Facebook doesn’t use any of that ... instead they use a model ... where you have a single definition of your schema that exists at your gateway." - Lee Byron

Federation can be a great fit if your organization isn't a monolith and values team autonomy. "[At Facebook] team autonomy is an anti-pattern," Lee joked. Teams that value autonomy or that may not share a unified language, on the other hand, may find a lot of value in federating.

Other panelists agreed that company culture and team structure play a big part in determining whether to use a monolith or microservice structure, which can also determine whether or not federation is a good fit for your project. Culture can be very difficult to change, and may not even be possible.

"Regardless of the decision the net result is very similar. … However it is that we arrive at that conclusion, it doesn’t matter that much, and so we should choose the one that is easier for your organization." - Lee Byron

What's new at GraphQL Foundation?

The Working Group, which contributes changes to the GraphQL spec, is about to run a vote for the leaders of their technical steering committee. This steering committee will be responsible for overseeing the Working Group.
The GraphQL Foundation has a bunch of new members and sponsors, which has allowed them to launch a brand new community grant program in order to redistribute some of those funds and encourage community-driven development. You can find the grant program here!
There's a newly released cut of the GraphQL spec!

That's a Wrap!

GraphQL Contributor Days is always a great way to keep your ear to the ground on what's coming in the GraphQL ecosystem. This month's event provided some fascinating insight into how some of the top companies in the world are using GraphQL. If you'd like to watch the full event and hear our panelists dive deeper on some of these topics (and more), you can find it here!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Star Richardson
Makeup artist turned self-taught software engineer and crypto enthusiast. Software Engineer at This Dot. Woman of a thousand interests and maker of many things.
@alicenstar @alicenstar

How to create and use custom GraphQL Scalars

How to create and use custom GraphQL Scalars In the realm of GraphQL, scalars form the bedrock of the type system, representing the most fundamental data types like strings, numbers, and booleans. As explored in our previous post, "Leveraging GraphQL Scalars to Enhance Your Schema," scalars play a pivotal role in defining how data is structured and validated. But what happens when the default scalars aren't quite enough? What happens when your application demands a data type as unique as its requirements? Enter the world of custom GraphQL scalars. These data types go beyond the conventional, offering the power and flexibility to tailor your schema to precisely match your application's unique needs. Whether handling complex data structures, enforcing specific data formats, or simply bringing clarity to your API, custom scalars open up a new realm of possibilities. In this post, we'll explore how to understand, create, and effectively utilize custom scalars in GraphQL. From conceptualization to implementation, we'll cover the essentials of extending your GraphQL toolkit, empowering you to transform abstract ideas into concrete, practical solutions. So, let's embark together on the journey of understanding and utilizing custom GraphQL scalars, enhancing and expanding the capabilities of your GraphQL schema. Understanding Custom Scalars Custom scalars in GraphQL extend beyond basic types like String or Int, allowing data to be defined, validated, and processed more precisely. They're instrumental when default types don't quite capture the complexity or specificity of the data, such as with specialized date formats or unique identifiers. The use of custom scalars brings several benefits: * Enhanced Clarity: They offer a clearer representation of what data looks like and how it behaves. * Built-in Validation: Data integrity is bolstered at the schema level. * Flexibility: They can be tailored to specific data handling needs, making your schema more adaptable and robust. With this understanding, we'll explore creating and integrating custom scalars into a GraphQL schema, turning theory into practice. Creating a Custom Scalar Defining a Custom Scalar in TypeScript: Creating a custom scalar in GraphQL with TypeScript involves defining its behavior through parsing, serialization, and validation functions. * Parsing: Transforms input data from the client into a server-understandable format. * Serializing: Converts server data back to a client-friendly format. * Validation: Ensures data adheres to the defined format or criteria. Example: A 'Color' Scalar in TypeScript The Color scalar will ensure that every color value adheres to a valid hexadecimal format, like #FFFFFF for white or #000000 for black: ` In this TypeScript implementation: * validateColors: a function that checks if the provided string matches the hexadecimal color format. * parseValue: a method function that converts the scalar’s value from the client into the server’s representation format - this method is called when a client provides the scalar as a variable. See parseValue docs for more information * serialize: a method function that converts the scalar’s server representation format to the client format, see serialize docs for more information * parseLiteral: similar to parseValue, this method function converts the scalar’s value from the client to the server’s representation format. Still, this method is called when the scalar is provided as a hard-coded argument (inline). See parseLiteral docs for more information In the upcoming section, we'll explore how to incorporate and validate these custom scalars within your schema, ensuring they function seamlessly in real-world scenarios. Integrating Custom Scalars into a Schema Incorporating the 'Color' Scalar After defining your custom Color scalar, the next crucial step is effectively integrating it into your GraphQL schema. This integration ensures that your GraphQL server recognizes and correctly utilizes the scalar. Step-by-Step Integration 1. Add the scalar to Type Definitions: Include the Color scalar in your GraphQL type definitions. This inclusion informs GraphQL about this new scalar type. 2. Resolver Mapping: Map your custom scalar type to its resolver. This connection is key for GraphQL to understand how to process this type during queries and mutations. ` 1. Use the scalar: Update your type to use the new custom scalar ` Testing the Integration With your custom Color scalar integrated, conducting thorough testing is vital. Ensure that your GraphQL server correctly handles the Color scalar, particularly in terms of accepting valid color formats and rejecting invalid ones. For demonstration purposes, I've adapted a creation mutation to include the primaryColor field. To keep this post focused and concise, I won't detail all the code changes here, but the following screenshots illustrate the successful implementation and error handling. Calling the mutation (createTechnology) successfully: Calling the mutation with forced fail (bad color hex): Conclusion The journey into the realm of custom GraphQL scalars reveals a world where data types are no longer confined to the basics. By creating and integrating scalars like the Color type, we unlock precision and specificity in our GraphQL schemas, which significantly enhance our applications' data handling capabilities. Custom scalars are more than just a technical addition; they testify to GraphQL's flexibility and power. They allow developers to express data meaningfully, ensuring that APIs are functional, intuitive, and robust. As we've seen, defining, integrating, and testing these scalars requires a blend of creativity and technical acumen. It encourages a deeper understanding of how data flows through your application and offers a chance to tailor that experience to your project's unique needs. So, as you embark on your GraphQL journey, consider the potential of custom scalars. Whether you're ensuring data integrity, enhancing API clarity, or simply making your schema a perfect fit for your application, the possibilities are as vast as they are exciting. Embrace the power of customization, and let your GraphQL schemas shine!...

Apr 10, 2024

5 mins

GraphQLJavaScript

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Introducing the new Serverless, GraphQL, Apollo Server, and Contentful Starter kit The team at This Dot Labs has released a brand new starter kit which includes the Serverless Framework, GraphQL, Apollo Server and Contentful configured and ready to go. This article will walk through how to set up the new kit, the key technologies used, and reasons why you would consider using this kit. Table of Contents - How to get started setting up the kit - Generate the project - Setup Contentful access - Setting up Docker - Starting the local server - How to Create the Technology Model in Contentful - How to seed the database with demo data - How to work with the migration scripts - Technologies included in this starter kit - Why use GraphQL? - Why use Contentful? - Why use Amazon Simple Queue Service (SQS)? - Why use Apollo Server? - Why use the Serverless Framework? - Why use Redis? - Why use the Jest testing framework? - Project structure - How to deploy your application - What can this starter kit be used for? - Conclusion How to get started setting up the kit Generate the project In the command line, you will need to start the starter.dev CLI by running the npx @this-dot/create-starter command. You can then select the Serverless Framework, Apollo Server, and Contentful CMS kit and name your new project. Then you will need to cd into your new project directory and install the dependencies using the tool of your choice (npm, yarn, or pnpm). Next, you will need to Run cp .env.example .env to copy the contents of the .env.example file into the .env file. Setup Contentful access You will first need to create an account on Contentful, if you don't have one already. Once you are logged in, you will need to create a new space. From there, go to Settings -> API keys and click on the Content Management Tokens tab. Next, click on the Generate personal token button and give your token a name. Copy your new Personal Access Token, and add it to the CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN variable. Then, go to Settings -> General settings to get the CONTENTFUL_SPACE_ID. The last step is to add those CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN and CONTENTFUL_SPACE_ID values to your .env file. Setting up Docker You will first need to install Docker Desktop if you don't have it installed already. Once installed, you can start up the Docker container with the npm run infrastructure:up command. Starting the local server While the Docker container is running, open up a new tab in the terminal and run npm run dev to start the development server. Open your browser to http://localhost:3000/dev/graphql to open up Apollo server. How to Create the Technology Model in Contentful To get started with the example model, you will first need to create the model in Contentful. 1. Log into your Contentful account 2. Click on the Content Model tab 3. Click on the Design your Content Modal button if this is your first modal 4. Create a new model called Technology 5. Add three new text fields called displayName, description and url 6. Save your new model How to seed the database with demo data This starter kit comes with a seeding script that pre-populates data for the Technology Content type. In the command line, run npm run db:seed which will add three new data entries into Contentful. If you want to see the results from seeding the database, you can execute a small GraphQL query using Apollo server. First, make sure Docker, and the local server(npm run dev) are running, and then navigate to http://localhost:3000/dev/graphql. Add the following query: ` When you run the query, you should see the following output. ` How to work with the migration scripts Migrations are a way to make changes to your content models and entries. This starter kit comes with a couple of migration scripts that you can study and run to make changes to the demo Technology model. These migration scripts are located in the scripts/migration directory. To get started, you will need to first install the contentful-cli. ` You can then login to Contentful using the contentful-cli. ` You will then need to choose the Contentful space where the Technology model is located. ` If you want to modify the existing demo content type, you can run the second migration script from the starter kit. ` If you want to build out more content models using the CLI, you can study the example code in the /scripts/migrations/01-create-technology-contentType.js file. From there, you can create a new migration file, and run the above contentful space migration command. If you want to learn more about migration in Contentful, then please check out the documentation. Technologies included in this starter kit Why use GraphQL? GraphQL is a query language for your API and it makes it easy to query all of the data you need in a single request. This starter kit uses GraphQL to query the data from our Contentful space. Why use Contentful? Contentful is a headless CMS that makes it easy to create and manage structured data. We have integrated Contentful into this starter kit to make it easy for you to create new entries in the database. Why use Amazon Simple Queue Service (SQS)? Amazon Simple Queue Service (SQS) is a queuing service that allows you to decouple your components and process and store messages in a scalable way. In this starter kit, an SQS message is sent by the APIGatewayProxyHandler using the sendMessage function, which is then stored in a queue called DemoJobQueue. The SQS handler sqs-handler polls this queue, and processes any message received. ` Why use Apollo Server? Apollo Server is a production-ready GraphQL server that works with any GraphQL client, and data source. When you run npm run dev and open the browser to http://localhost:3000/dev/graphql, you will be able to start querying your Contentful data in no time. Why use the Serverless Framework? The Serverless Framework is used to help auto-scale your application by using AWS Lambda functions. In the starter kit, you will find a serverless.yml file, which acts as a configuration for the CLI and allows you to deploy your code to your chosen provider. This starter kit also includes the following plugins: - serverless-offline - allows us to deploy our application locally to speed up development cycles. - serverless-plugin-typescript - allows the use of TypeScript with zero-config. - serverless-dotenv-plugin - preloads function environment variables into the Serverless Framework. Why use Redis? Redis is an open-source in-memory data store that stores data in the server memory. This starter kit uses Redis to cache the data to reduce the API response times and rate limiting. When you make a new request, those new requests will be retrieved from the Redis cache. Why use the Jest testing framework? Jest is a popular testing framework that works well for creating unit tests. You can see some example test files under the src/schema/technology directory. You can use the npm run test command to run all of the tests. Project structure Inside the src directory, you will find the following structure: ` This given structure makes it easy to find all of the code and tests related to that specific component. This structure also follows the single responsibility principle which means that each file has a single purpose. How to deploy your application The Serverless Framework needs access to your cloud provider account so that it can create and manage resources on your behalf. You can follow the guide to get started. Steps to get started: 1. Sign up for an AWS account 2. Create an IAM User and Access Key 3. Export your AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY credentials. ` 4. Deploy your application on AWS Lambda: ` 5. To deploy a single function, run: ` To stop your Serverless application, run: ` For more information on Serverless deployment, check out this article. What can this starter kit be used for? This starter kit is very versatile, and can be used with a front-end application for a variety of situations. Here are some examples: - personal developer blog - small e-commerce application Conclusion In this article, we looked at how we can get started using the Serverless, GraphQL, Apollo Server, and Contentful Starter kit. We also looked at the different technologies used in the kit, and why they were chosen. Lastly, we looked at how to deploy our application using AWS. I hope you enjoy working with our new starter kit!...

Jun 2, 2023

7 mins

GraphQL

Benefits of Software Apprenticeship & How to Make the Most of Yours

It’s no surprise that over the past year, many have started switching careers into tech. I was one of thousands of people that hopped on the “Learn to Code” train last year after losing my retail job. Being without a college degree, I looked into programming because it was one of the few industries where you could teach yourself the necessary skills without a long and expensive college education. As with many things though, the process of learning to code, and finding a job, proved more difficult than expected. About two months into a fruitless job search, a mentor of mine told me about This Dot and their Apprentice Program that had helped her get started as a self-taught software engineer. I was so excited to find an approachable entry point into tech for self-taught folks like myself! What is an apprenticeship? So what is an apprenticeship, and how does it differ from an internship? As I understand it, an apprenticeship is a program that provides hands-on work experience with the explicit goal of placing you in a job. An internship is more focused on general exposure to a work environment, or industry, without the explicit goal of hiring or placing you at the end. Another major difference is that most internships will require you to be an active college student pursuing a degree, while apprenticeships are generally more accommodating of unconventional backgrounds. Why do an apprenticeship? These are some of the key reasons I decided to pursue an apprenticeship at This Dot Labs. Keep in mind that every apprenticeship and every company is different, and the reasons I’ve listed here are specific to my experience in This Dot’s Apprentice Program. 1. Mentorship Opportunities Before I started my apprenticeship at This Dot, I was told I would be assigned a mentor that would meet with me once or twice a week. I didn’t realize that nearly all of my teammates and managers would also become my mentors. If I have a question, someone on the team is bound to have the answer, and everyone is more than willing to help. I’m only a few weeks into the apprentice program, but the meetings I’ve had with my mentor, teammates, and managers have already helped grow my skills immensely. 2. Room to Learn and Grow The whole purpose of an apprenticeship is to give someone the room to ask questions, fail, learn, and grow. In my first week as an apprentice, I was absolutely terrified of asking too many “stupid” questions. I struggled trying to do things on my own. Over and over, my managers reassured and encouraged me to keep asking more. They understand what it’s like starting out as a dev in your first job, and they are there to help you through every struggle. I quickly learned that if I ask questions early on instead of struggling for hours, I actually end up getting more work done, and being a bigger help to my team. They strongly encourage you to follow your interests and curiosities outside of software development at This Dot as well. I’ve already been given opportunities to try out other areas of interest in tech, such as Developer Relations (DevRel). In my first few weeks, I’ve been able to do things I’ve never tried before, like speaking on a podcast, writing blog posts (like this one!) and tweets, and moderating a panel at MagnoliaJS Conference. This room to experiment is a rare and valuable opportunity for an early-career developer. 3. Hands-on Experience Working on high-impact projects for major companies, and actually being responsible for the outcomes of these projects, is incredibly rewarding and validating. Being given a high level of autonomy, and the opportunity to “rise to the occasion” will grow your skills faster than any internship where you might be given tasks unrelated to your area of interest. The opportunity to build confidence, and validate your skills so early in your career, is invaluable. 4. The Team This point is obviously specific to my experience at This Dot, but it is so important to find a company that meshes well with your personality and values. This Dot greatly values good people, good work, personal growth, and a diverse team. I’m exposed to a lot of different people with different backgrounds and unique perspectives at work, which has been immensely valuable. This Dot even has a *Hire the Fempire* program that works with companies to hire more women in tech through their apprentice program. 5. An Accessible Option This is perhaps the most important point to me and the reason that apprenticeships are so invaluable: They offer an easier way to break into the tech industry for people that otherwise might not have the resources to be able to pursue a degree. They allow people with unconventional backgrounds to get real job experience, and change the trajectory of their lives. How can I make the most of my apprenticeship? You've done it! You've made it past the barrier and gotten your first tech job! Here are some ways I plan to make the absolute most of my time as an apprentice. 1. Ask Questions Now is the time to ask a lot of questions, and when I say "a lot", I mean *a lot*. If you are like the majority of people who experience impostor syndrome, this is something you will need to push past very early on. It will only hold you back. If, like me, you are terrified of sounding "stupid" or being found out as a fraud, try to reframe how you view asking questions. You are not asking a stupid question. You are simply trying to get unblocked, to allow yourself to do more awesome work. Don't stifle your own progress because you're afraid of appearing less knowledgeable than you are. If you're still worried about overloading your teammates or mentors with lots of questions, try batching your questions. Keep a list of questions you'd like to ask, and ask several at a time rather than spreading them out throughout the day or week. Lastly, be sure you know how to ask a good question, and always show gratitude to the person who's helping you. 2. Go Out of Your Way to Meet People In the first few weeks, I made sure to set up a short video meeting with all my managers, teammates- anyone I would be working with directly. These are the people that will celebrate wins with you, and help you when you're struggling. Once you get to know people long enough, you'll probably start to see that everyone has a "thing" they're particularly passionate about. You'll find out who to go to for React or Angular help, who to go to for GraphQL or Elixir knowledge. Fostering good, genuine relationships is incredibly important if you want to have a meaningful career (and life). 3. Don't Hide Your Struggles If you're struggling, don't be afraid to ask for help. If you followed my last tip for building relationships, hopefully you'll have found who you can go to for emotional support. Talking out your struggles can be one of the quickest ways to move past them, and your confidant may have their own personal experiences that can help you with yours. 4. Stay Open to Criticism Feedback is the fastest way to level up as a developer and human being. To use feedback most effectively, it's important to separate yourself from your work. If someone offers you feedback that is delivered in a not-so-nice way, you can still take something constructive from it, and use it to improve your work. In a lot of development work, it can actually be hard to know how or what to improve, so I try to view criticism as a blessing in disguise, and be grateful for being given some direction. 5. Set Goals and Track Your Progress Speaking of direction, it's important to have goals to work towards in many aspects of life. Set some short and long term goals for your apprenticeship, and share them with your mentors. If your mentors are good mentors, they'll support you in achieving these goals. Along with this, it's also important to have some way to track your progress. Some people like to journal, some people keep a Google doc or a Notion page. Personally, I've been sending myself a weekly email to track my progress. Point is: find a way to track your progress, and keep up with it regularly. Closing Thoughts I hope this post was helpful and inspiring to anyone trying to break into the tech industry! My hope for the future is that more companies will adopt apprentice programs, and structure them in a way that empowers early-career devs to ask questions, fail fast and fail forward, and be fearless learners. Tech still has a major diversity problem, and a lot of marginalized groups fall into the category of those with unconventional career backgrounds. If more companies offered apprenticeships, it would be a great step in the right direction for bringing more diversity into tech....

Jun 10, 2021

6 mins

Career development

Internationalization in Next.js with next-intl

Internationalization in Next.js with next-intl Internationalization (i18n) is essential for providing a multi-language experience for global applications. next-intl integrates well with Next.js’ App Router, handling i18n routing, locale detection, and dynamic configuration. This guide will walk you through setting up i18n in Next.js using next-intl for URL-based routing, user-specific settings, and domain-based locale routing. Getting Started First, create a Next.js app with the App Router and install next-intl: ` Next, configure next-intl in the next.config.ts file to provide a request-specific i18n configuration for Server Components: ` Without i18n Routing Setting up an app without i18n routing integration can be advantageous in scenarios where you want to provide a locale to next-intl based on user-specific settings or when your app supports only a single language. This approach offers the simplest way to begin using next-intl, as it requires no changes to your app’s structure, making it an ideal choice for straightforward implementations. ` Here’s a quick explanation of each file's role: * translations/: Stores different translations per language (e.g., en.json for English, es.json for Spanish). Organize this as needed, e.g., translations/en/common.json. * request.ts: Manages locale-based configuration scoped to each request. Setup request.ts for Request-Specific Configuration Since we will be using features from next-intl in Server Components, we need to add the following configuration in i18n/request.ts: ` Here, we define a static locale and use that to determine which translation file to import. The imported JSON data is stored in the message variable, and is returned together with the locale so that we can access them from various components in the application. Using Translation in RootLayout Inside RootLayout, we use getLocale() to retrieve the static locale and set the document language for SEO and pass translations to NextIntlClientProvider: ` Note that NextIntlClientProvider automatically inherits configuration from i18n/request.ts here, but messages must be explicitly passed. Now you can use translations and other functionality from next-intl in your components: ` In case of async components, you can use the awaitable getTranslations function instead: ` And with that, you have i18n configured and working on your application! \ Now, let’s take it a step further by introducing routing. \ With i18n Routing To set up i18n routing, we need a file structure that separates each language configuration and translation file. Below is the recommended structure: ` We updated the earlier structure to include some files that we require for routing: * routing.ts: Sets up locales, default language, and routing, shared between middleware and navigation. * middleware.ts: Handles URL rewrites and locale negotiation. * app/[locale]/: Creates dynamic routes for each locale like /en/about and /es/about. Define Routing Configuration in i18n/routing.ts The routing.ts file configures supported locales and the default locale, which is referenced by middleware.ts and other navigation functions: ` This configuration lets Next.js handle URL paths like /about, with locale management managed by next-intl. Update request.ts for Request-Specific Configuration We need to update the getRequestConfig function from the above implementation in i18n/request.ts. ` Here, request.ts ensures that each request loads the correct translation files based on the user’s locale or falls back to the default. Setup Middleware for Locale Matching The middleware.ts file matches the locale based on the request: ` Middleware handles locale matches and redirects to localized paths like /en or /es. Updating the RootLayout file Inside RootLayout, we use the locale from params (matched by middleware) instead of calling getLocale() ` The locale we get from the params was matched in the middleware.ts file and we use that here to set the document language for SEO purposes. Additionally, we used this file to pass configuration from i18n/request.ts to Client Components through NextIntlClientProvider. Note: When using the above setup with i18n routing, next-intl will currently opt into dynamic rendering when APIs like useTranslations are used in Server Components. next-intl provides a temporary API that can be used to enable static rendering. Static Rendering for i18n Routes For apps with dynamic routes, use generateStaticParams to pass all possible locale values, allowing Next.js to render at build time: ` next-intl provides an API setRequestLocale that can be used to distribute the locale that is received via params in layouts and pages for usage in all Server Components that are rendered as part of the request. You need to call this function in every layout/page that you intend to enable static rendering for since Next.js can render layouts and pages independently. ` Note: Call setRequestLocale before invoking useTranslations or getMessages or any next-intl functions. Domain Routing For domain-specific locale support, use the domains setting to map domains to locales, such as us.example.com/en or ca.example.com/fr. ` This setup allows you to serve localized content based on domains. Read more on domain routing here. Conclusion Setting up internationalization in Next.js with next-intl provides a modular way to handle URL-based routing, user-defined locales, and domain-specific configurations. Whether you need URL-based routing or a straightforward single-locale setup, next-intl adapts to fit diverse i18n needs. With these tools, your app will be ready to deliver a seamless multi-language experience to users worldwide....

Apr 11, 2025

4 mins

NextJSAccessibility

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

GraphQL Contributor Days | December 2021

Panelists

Community Showcase & Updates

GraphQL Yoga (Uri Goldshtein)

RescriptRelay CLI (Gabriel Nordeborn)

GraphQL Learning

Authorization & Security

Federation

What's new at GraphQL Foundation?

That's a Wrap!

Star Richardson

You might also like

How to create and use custom GraphQL Scalars

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Benefits of Software Apprenticeship & How to Make the Most of Yours

Internationalization in Next.js with next-intl

Let's innovate together!

You might also like

How to create and use custom GraphQL Scalars

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Benefits of Software Apprenticeship & How to Make the Most of Yours

Internationalization in Next.js with next-intl