Skip to content

MIGRATION_V3_TO_V4.md

Latest commit

 

History

History
388 lines (286 loc) · 9.23 KB

MIGRATION_V3_TO_V4.md

File metadata and controls

388 lines (286 loc) · 9.23 KB

Migration Guide: Upgrading from v3 to v4

This guide will help you upgrade your application from aws-appsync-auth-link v3.x and aws-appsync-subscription-link v3.x to v4.x.

Overview

Version 4 of the AWS AppSync Apollo links brings compatibility with Apollo Client v4 and includes several important updates:

  • ✅ Apollo Client v4 support
  • ✅ GraphQL v16 support
  • ✅ Dual module format (ESM + CommonJS)
  • ✅ Browser environment compatibility improvements
  • ✅ RxJS v7+ peer dependency
  • ✅ UUID peer dependency (for subscription-link)

Breaking Changes

1. Apollo Client v4 Required

v3:

{
  "dependencies": {
    "@apollo/client": "^3.2.0"
  }
}

v4:

{
  "dependencies": {
    "@apollo/client": "^4.0.0"
  }
}

You must upgrade to Apollo Client v4. Follow the official Apollo Client v4 migration guide for details on Apollo-specific changes.

2. GraphQL v16 Required

v4 requires GraphQL v16 (previously v15 was supported).

Update your dependencies:

npm install graphql@^16.0.0
# or
yarn add graphql@^16.0.0

3. RxJS v7+ Peer Dependency Added

Both packages now have RxJS as a peer dependency. If you don't already have it installed:

npm install rxjs@^7.0.0
# or
yarn add rxjs@^7.0.0

4. UUID Peer Dependency Added (subscription-link only)

The aws-appsync-subscription-link package now requires UUID as a peer dependency. If you don't already have it installed:

npm install uuid@^8.0.0
# or
yarn add uuid@^8.0.0

Note: UUID v9 and v10 are also supported if you prefer newer versions.

5. Minimum Node.js Version

Due to Apollo Client v4 requirements, ensure you're using:

  • Node.js 14.16+ or higher

Step-by-Step Migration

Step 1: Update Package Dependencies

Update your package.json:

{
  "dependencies": {
    "@apollo/client": "^4.0.0",
    "aws-appsync-auth-link": "^4.0.0",
    "aws-appsync-subscription-link": "^4.0.0",
    "graphql": "^16.0.0",
    "rxjs": "^7.0.0",
    "uuid": "^8.0.0"
  }
}

Note: If you're only using aws-appsync-auth-link (queries/mutations without subscriptions), you don't need to install uuid.

Then install:

npm install
# or
yarn install

Step 2: Update Apollo Client Imports

Apollo Client v4 has some import changes. The most common:

Before (v3):

import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';

After (v4):

// Same imports work, but check Apollo's migration guide for any
// specific features you're using
import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';

Step 3: Update Your Client Setup

Your client setup remains largely the same:

import { createAuthLink } from 'aws-appsync-auth-link';
import { createSubscriptionHandshakeLink } from 'aws-appsync-subscription-link';
import {
  ApolloClient,
  InMemoryCache,
  HttpLink,
  ApolloLink,
} from '@apollo/client';

const url = 'https://xxxxx.appsync-api.us-east-1.amazonaws.com/graphql';
const region = 'us-east-1';

const auth = {
  type: 'API_KEY', // or 'AWS_IAM' | 'AMAZON_COGNITO_USER_POOLS' | 'OPENID_CONNECT' | 'AWS_LAMBDA'
  apiKey: 'da2-xxxxxxxxxxxxxxxxxxxxxxxxxx',
  // For Cognito or OIDC:
  // jwtToken: async () => 'your-jwt-token',
  // For IAM:
  // credentials: async () => credentials,
};

const httpLink = new HttpLink({ uri: url });

const link = ApolloLink.from([
  createAuthLink({ url, region, auth }),
  createSubscriptionHandshakeLink({ url, region, auth }, httpLink),
]);

const client = new ApolloClient({
  link,
  cache: new InMemoryCache(),
});

Common Issues & Solutions

Issue: "Dynamic require of 'buffer' is not supported"

Solution: This issue has been fixed in v4. If you're still seeing it, ensure you've:

  1. Installed v4.0.0 or higher
  2. Cleared your node_modules and reinstalled
  3. Rebuilt your application

Issue: Import errors with Vite or other ESM bundlers

Solution: v4 now properly supports ESM. Ensure you're using the latest version and that your bundler is configured to resolve the exports field in package.json.

Issue: TypeScript errors after upgrade

Solution:

  1. Update @types/graphql if you have it installed
  2. Ensure your tsconfig.json has proper module resolution:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Issue: "Cannot find module 'uuid'" or "Module not found: uuid"

Solution: The uuid package is now a peer dependency for aws-appsync-subscription-link. Install it:

npm install uuid@^8.0.0
# or
yarn add uuid@^8.0.0

If you're only using aws-appsync-auth-link for queries/mutations, you don't need uuid.

Apollo Client v4 Specific Changes

When migrating to Apollo Client v4, be aware of these key changes:

1. Observable Implementation

Apollo Client v4 uses RxJS instead of zen-observable:

// v3 - zen-observable
import { Observable } from 'zen-observable-ts';

// v4 - RxJS (usually not needed in user code)
import { Observable } from 'rxjs';

2. Cache API Changes

Some cache methods have changed. Refer to the Apollo Client v4 migration guide for details.

Testing Your Migration

After upgrading, test these key areas:

1. Authentication

Test all auth types you're using:

// API Key
const auth = {
  type: 'API_KEY',
  apiKey: 'your-api-key',
};

// IAM
const auth = {
  type: 'AWS_IAM',
  credentials: async () => ({
    accessKeyId: 'xxx',
    secretAccessKey: 'xxx',
    sessionToken: 'xxx',
  }),
};

// Cognito User Pools
const auth = {
  type: 'AMAZON_COGNITO_USER_POOLS',
  jwtToken: async () => 'your-jwt-token',
};

// OIDC
const auth = {
  type: 'OPENID_CONNECT',
  jwtToken: async () => 'your-jwt-token',
};

// Lambda
const auth = {
  type: 'AWS_LAMBDA',
  token: async () => 'your-token',
};

2. Queries

import { gql, useQuery } from '@apollo/client';

const GET_ITEMS = gql`
  query GetItems {
    listItems {
      items {
        id
        name
      }
    }
  }
`;

function MyComponent() {
  const { loading, error, data } = useQuery(GET_ITEMS);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return <div>{/* Render your data */}</div>;
}

3. Mutations

import { gql, useMutation } from '@apollo/client';

const CREATE_ITEM = gql`
  mutation CreateItem($input: CreateItemInput!) {
    createItem(input: $input) {
      id
      name
    }
  }
`;

function MyComponent() {
  const [createItem, { data, loading, error }] = useMutation(CREATE_ITEM);

  const handleCreate = () => {
    createItem({ variables: { input: { name: 'New Item' } } });
  };

  return <button onClick={handleCreate}>Create</button>;
}

4. Subscriptions

import { gql, useSubscription } from '@apollo/client';

const ON_CREATE_ITEM = gql`
  subscription OnCreateItem {
    onCreateItem {
      id
      name
    }
  }
`;

function MyComponent() {
  const { data, loading, error } = useSubscription(ON_CREATE_ITEM);

  if (loading) return <p>Listening...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return <div>{/* Render subscription data */}</div>;
}

React Native Considerations

If you're using React Native:

  1. Ensure you have the proper polyfills for fetch and WebSocket
  2. Apollo Client v4 may have additional React Native requirements - check the Apollo docs

Rollback Strategy

If you encounter issues, you can rollback to v3:

npm install @apollo/client@^3.2.0 aws-appsync-auth-link@^3.0.0 aws-appsync-subscription-link@^3.0.0 graphql@^15.0.0
# or
yarn add @apollo/client@^3.2.0 aws-appsync-auth-link@^3.0.0 aws-appsync-subscription-link@^3.0.0 graphql@^15.0.0

Note: In v3, uuid was bundled with aws-appsync-subscription-link, so you can uninstall it if you added it for v4.

Additional Resources

Need Help?

If you encounter issues during migration:

  1. Check the GitHub Issues
  2. Review the AWS AppSync Forum
  3. Open a new issue with:
    • Your package versions
    • Error messages
    • Minimal reproduction code

What's New in v4?

Beyond the breaking changes, v4 includes:

  • Better Bundle Size: Proper externalization of dependencies (including uuid) reduces bundle size
  • Improved Browser Compatibility: No more Node.js polyfills in browser bundles
  • Modern Module Format: Full ESM support with backwards-compatible CommonJS
  • Updated Dependencies: Latest security patches and improvements
  • Optimized Peer Dependencies: Common packages like uuid are now peer dependencies to avoid duplication

Last Updated: 2025-10-12