Skip to content

feat(nextjs): Promote useRunAfterProductionCompileHook to non-experimental build option #17721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 22, 2025
Merged

feat(nextjs): Promote useRunAfterProductionCompileHook to non-experimental build option #17721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e90bcde
promote flag to non-experimental
chargome Sep 20, 2025
f60a7cd
fix tests
chargome Sep 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions packages/nextjs/src/config/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -501,22 +501,23 @@ export type SentryBuildOptions = {
*/
disableSentryWebpackConfig?: boolean;

/**
* When true (and Next.js >= 15), use the runAfterProductionCompile hook to consolidate sourcemap uploads
* into a single operation after builds complete, reducing build time.
*
* When false, use the traditional approach of uploading sourcemaps during each webpack build. For Turbopack no sourcemaps will be uploaded.
*
* @default false
*/
useRunAfterProductionCompileHook?: boolean;

/**
* Contains a set of experimental flags that might change in future releases. These flags enable
* features that are still in development and may be modified, renamed, or removed without notice.
* Use with caution in production environments.
*/
_experimental?: Partial<{
/**
* When true (and Next.js >= 15), use the runAfterProductionCompile hook to consolidate sourcemap uploads
* into a single operation after turbopack builds complete, reducing build time.
*
* When false, use the traditional approach of uploading sourcemaps during each webpack build.
*
* @default false
*/
useRunAfterProductionCompileHook?: boolean;
thirdPartyOriginStackFrames: boolean;
thirdPartyOriginStackFrames?: boolean;
}>;
};

Expand Down
4 changes: 2 additions & 2 deletions packages/nextjs/src/config/withSentryConfig.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,7 +294,7 @@ function getFinalConfigObject(
}
}

if (userSentryOptions?._experimental?.useRunAfterProductionCompileHook === true && supportsProductionCompileHook()) {
if (userSentryOptions?.useRunAfterProductionCompileHook === true && supportsProductionCompileHook()) {
if (incomingUserNextConfigObject?.compiler?.runAfterProductionCompile === undefined) {
incomingUserNextConfigObject.compiler ??= {};
incomingUserNextConfigObject.compiler.runAfterProductionCompile = async ({ distDir }) => {
Expand Down Expand Up @@ -379,7 +379,7 @@ function getFinalConfigObject(
releaseName,
routeManifest,
nextJsVersion,
useRunAfterProductionCompileHook: userSentryOptions._experimental?.useRunAfterProductionCompileHook,
useRunAfterProductionCompileHook: userSentryOptions?.useRunAfterProductionCompileHook,
}),
...(isTurbopackSupported && isTurbopack
? {
Expand Down
3 changes: 1 addition & 2 deletions packages/nextjs/test/config/testUtils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,7 @@ export async function materializeFinalWebpackConfig(options: {
routeManifest: options.routeManifest,
nextJsVersion: options.nextJsVersion,
useRunAfterProductionCompileHook:
options.useRunAfterProductionCompileHook ??
options.sentryBuildTimeOptions?._experimental?.useRunAfterProductionCompileHook,
options.useRunAfterProductionCompileHook ?? options.sentryBuildTimeOptions?.useRunAfterProductionCompileHook,
});

// call it to get concrete values for comparison
Expand Down
8 changes: 2 additions & 6 deletions packages/nextjs/test/config/webpack/constructWebpackConfig.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,7 @@ describe('constructWebpackConfigFunction()', () => {
incomingWebpackConfig: serverWebpackConfig,
incomingWebpackBuildContext: serverBuildContext,
sentryBuildTimeOptions: {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
},
});

Expand All @@ -128,9 +126,7 @@ describe('constructWebpackConfigFunction()', () => {
incomingWebpackConfig: serverWebpackConfig,
incomingWebpackBuildContext: serverBuildContext,
sentryBuildTimeOptions: {
_experimental: {
useRunAfterProductionCompileHook: false,
},
useRunAfterProductionCompileHook: false,
},
});

Expand Down
139 changes: 20 additions & 119 deletions packages/nextjs/test/config/withSentryConfig.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -769,27 +769,27 @@ describe('withSentryConfig', () => {
vi.restoreAllMocks();
});

it('sets up runAfterProductionCompile hook when experimental flag is enabled and version is supported', () => {
it('sets up runAfterProductionCompile hook when flag is enabled and version is supported', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
};

const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);
// Use a clean copy of the config to avoid test interference
const cleanConfig = { ...exportedNextConfig };
delete cleanConfig.compiler;

const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
});

it('does not set up hook when experimental flag is disabled', () => {
it('does not set up hook when flag is disabled', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: false,
},
useRunAfterProductionCompileHook: false,
};

const cleanConfig = { ...exportedNextConfig };
Expand All @@ -804,9 +804,7 @@ describe('withSentryConfig', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(false);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
};

const cleanConfig = { ...exportedNextConfig };
Expand All @@ -829,9 +827,7 @@ describe('withSentryConfig', () => {
};

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
};

const finalConfig = materializeFinalNextConfig(configWithExistingHook, undefined, sentryOptions);
Expand All @@ -852,9 +848,7 @@ describe('withSentryConfig', () => {
};

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
};

materializeFinalNextConfig(configWithInvalidHook, undefined, sentryOptions);
Expand All @@ -873,9 +867,7 @@ describe('withSentryConfig', () => {
delete configWithoutCompiler.compiler;

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
};

const finalConfig = materializeFinalNextConfig(configWithoutCompiler, undefined, sentryOptions);
Expand All @@ -890,126 +882,35 @@ describe('withSentryConfig', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
};

const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);

delete process.env.TURBOPACK;
});

it('works with webpack builds when TURBOPACK env is not set', () => {
delete process.env.TURBOPACK;
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
};

const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
});
});

describe('experimental flag handling', () => {
afterEach(() => {
vi.restoreAllMocks();
});

it('respects useRunAfterProductionCompileHook: true', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
useRunAfterProductionCompileHook: true,
};

// Use a clean copy of the config to avoid test interference
const cleanConfig = { ...exportedNextConfig };
delete cleanConfig.compiler;

const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
});

it('respects useRunAfterProductionCompileHook: false', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: false,
},
};

const cleanConfig = { ...exportedNextConfig };
delete cleanConfig.compiler;

const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeUndefined();
});

it('does not set up hook when experimental flag is undefined', () => {
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
// useRunAfterProductionCompileHook not specified
},
};

const cleanConfig = { ...exportedNextConfig };
delete cleanConfig.compiler;

const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeUndefined();
delete process.env.TURBOPACK;
});

it('does not set up hook when _experimental is undefined', () => {
it('works with webpack builds when TURBOPACK env is not set', () => {
delete process.env.TURBOPACK;
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
// no _experimental property
useRunAfterProductionCompileHook: true,
};

// Use a clean copy of the config to avoid test interference
const cleanConfig = { ...exportedNextConfig };
delete cleanConfig.compiler;

const finalConfig = materializeFinalNextConfig(cleanConfig, undefined, sentryOptions);

expect(finalConfig.compiler?.runAfterProductionCompile).toBeUndefined();
});

it('combines experimental flag with other configurations correctly', () => {
process.env.TURBOPACK = '1';
vi.spyOn(util, 'getNextjsVersion').mockReturnValue('15.4.1');
vi.spyOn(util, 'supportsProductionCompileHook').mockReturnValue(true);

const sentryOptions = {
_experimental: {
useRunAfterProductionCompileHook: true,
},
sourcemaps: {},
tunnelRoute: '/tunnel',
};

const finalConfig = materializeFinalNextConfig(exportedNextConfig, undefined, sentryOptions);

// Should have both turbopack sourcemap config AND runAfterProductionCompile hook
expect(finalConfig.productionBrowserSourceMaps).toBe(true);
expect(finalConfig.compiler?.runAfterProductionCompile).toBeInstanceOf(Function);
expect(finalConfig.rewrites).toBeInstanceOf(Function);

delete process.env.TURBOPACK;
});
});
});