Skip to content

feat(nuxt): Base decision on source maps upload only on Nuxt source map settings #15859

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 9 commits into from
Apr 3, 2025
Merged

feat(nuxt): Base decision on source maps upload only on Nuxt source map settings #15859

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
015bcc1
wip: revamped source maps for nuxt
s1gr1d Mar 27, 2025
6748475
clean up code 1
s1gr1d Mar 27, 2025
0d34bb9
add tests 1
s1gr1d Mar 28, 2025
f56e7d8
add tests 2
s1gr1d Mar 28, 2025
3aafc13
add test for deleteFilesAfterUpload
s1gr1d Mar 28, 2025
878b13d
remove white spaces
s1gr1d Mar 28, 2025
a9165dc
add debug log to add rollup plugin
s1gr1d Mar 28, 2025
0909745
Merge branch 'develop' into sig/source-maps-nuxt
s1gr1d Mar 28, 2025
479aa8f
update "enabled" log
s1gr1d Apr 3, 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
257 changes: 176 additions & 81 deletions packages/nuxt/src/vite/sourceMaps.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,36 +3,91 @@ import { consoleSandbox } from '@sentry/core';
import { type SentryRollupPluginOptions, sentryRollupPlugin } from '@sentry/rollup-plugin';
import { type SentryVitePluginOptions, sentryVitePlugin } from '@sentry/vite-plugin';
import type { NitroConfig } from 'nitropack';
import type { OutputOptions } from 'rollup';
import type { SentryNuxtModuleOptions } from '../common/types';

/**
* Whether the user enabled (true, 'hidden', 'inline') or disabled (false) source maps
*/
export type UserSourceMapSetting = 'enabled' | 'disabled' | 'unset' | undefined;

/** A valid source map setting */
export type SourceMapSetting = boolean | 'hidden' | 'inline';

/**
* Setup source maps for Sentry inside the Nuxt module during build time (in Vite for Nuxt and Rollup for Nitro).
*/
export function setupSourceMaps(moduleOptions: SentryNuxtModuleOptions, nuxt: Nuxt): void {
const isDebug = moduleOptions.debug;

const sourceMapsUploadOptions = moduleOptions.sourceMapsUploadOptions || {};
const sourceMapsEnabled = sourceMapsUploadOptions.enabled ?? true;

// In case we overwrite the source map settings, we default to deleting the files
let shouldDeleteFilesFallback = { client: true, server: true };

nuxt.hook('modules:done', () => {
if (sourceMapsEnabled && !nuxt.options.dev) {
changeNuxtSourceMapSettings(nuxt, moduleOptions);
// Changing this setting will propagate:
// - for client to viteConfig.build.sourceMap
// - for server to viteConfig.build.sourceMap and nitro.sourceMap
// On server, nitro.rollupConfig.output.sourcemap remains unaffected from this change.

// ONLY THIS nuxt.sourcemap.(server/client) setting is the one Sentry will eventually overwrite with 'hidden'
const previousSourceMapSettings = changeNuxtSourceMapSettings(nuxt, moduleOptions);

shouldDeleteFilesFallback = {
client: previousSourceMapSettings.client === 'unset',
server: previousSourceMapSettings.server === 'unset',
};

if (
isDebug &&
!sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload &&
(shouldDeleteFilesFallback.client || shouldDeleteFilesFallback.server)
) {
consoleSandbox(() =>
// eslint-disable-next-line no-console
console.log(
"[Sentry] As Sentry enabled `'hidden'` source maps, source maps will be automatically deleted after uploading them to Sentry.",
),
);
}
}
});

nuxt.hook('vite:extendConfig', async (viteConfig, _env) => {
nuxt.hook('vite:extendConfig', async (viteConfig, env) => {
if (sourceMapsEnabled && viteConfig.mode !== 'development') {
const previousUserSourceMapSetting = changeViteSourceMapSettings(viteConfig, moduleOptions);
const runtime = env.isServer ? 'server' : env.isClient ? 'client' : undefined;
const nuxtSourceMapSetting = extractNuxtSourceMapSetting(nuxt, runtime);

viteConfig.build = viteConfig.build || {};
const viteSourceMap = viteConfig.build.sourcemap;

// Vite source map options are the same as the Nuxt source map config options (unless overwritten)
validateDifferentSourceMapSettings({
nuxtSettingKey: `sourcemap.${runtime}`,
nuxtSettingValue: nuxtSourceMapSetting,
otherSettingKey: 'viteConfig.build.sourcemap',
otherSettingValue: viteSourceMap,
});

if (isDebug) {
consoleSandbox(() => {
if (!runtime) {
// eslint-disable-next-line no-console
console.log("[Sentry] Cannot detect runtime (client/server) inside hook 'vite:extendConfig'.");
} else {
// eslint-disable-next-line no-console
console.log(`[Sentry] Adding Sentry Vite plugin to the ${runtime} runtime.`);
}
});
}

// Add Sentry plugin
// Add Sentry plugin
// Vite plugin is added on the client and server side (hook runs twice)
// Nuxt client source map is 'false' by default. Warning about this will be shown already in an earlier step, and it's also documented that `nuxt.sourcemap.client` needs to be enabled.
viteConfig.plugins = viteConfig.plugins || [];
viteConfig.plugins.push(
sentryVitePlugin(getPluginOptions(moduleOptions, previousUserSourceMapSetting === 'unset')),
);
viteConfig.plugins.push(sentryVitePlugin(getPluginOptions(moduleOptions, shouldDeleteFilesFallback)));
}
});

Expand All @@ -49,11 +104,19 @@ export function setupSourceMaps(moduleOptions: SentryNuxtModuleOptions, nuxt: Nu
nitroConfig.rollupConfig.plugins = [nitroConfig.rollupConfig.plugins];
}

const previousUserSourceMapSetting = changeRollupSourceMapSettings(nitroConfig, moduleOptions);
validateNitroSourceMapSettings(nuxt, nitroConfig, moduleOptions);

if (isDebug) {
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.log('[Sentry] Adding Sentry Rollup plugin to the server runtime.');
});
}

// Add Sentry plugin
// Runs only on server-side (Nitro)
nitroConfig.rollupConfig.plugins.push(
sentryRollupPlugin(getPluginOptions(moduleOptions, previousUserSourceMapSetting === 'unset')),
sentryRollupPlugin(getPluginOptions(moduleOptions, shouldDeleteFilesFallback)),
);
}
});
Expand All @@ -73,15 +136,29 @@ function normalizePath(path: string): string {
*/
export function getPluginOptions(
moduleOptions: SentryNuxtModuleOptions,
deleteFilesAfterUpload: boolean,
shouldDeleteFilesFallback?: { client: boolean; server: boolean },
): SentryVitePluginOptions | SentryRollupPluginOptions {
const sourceMapsUploadOptions = moduleOptions.sourceMapsUploadOptions || {};

if (typeof sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload === 'undefined' && deleteFilesAfterUpload) {
const shouldDeleteFilesAfterUpload = shouldDeleteFilesFallback?.client || shouldDeleteFilesFallback?.server;
const fallbackFilesToDelete = [
...(shouldDeleteFilesFallback?.client ? ['.*/**/public/**/*.map'] : []),
...(shouldDeleteFilesFallback?.server
? ['.*/**/server/**/*.map', '.*/**/output/**/*.map', '.*/**/function/**/*.map']
: []),
];

if (
typeof sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload === 'undefined' &&
shouldDeleteFilesAfterUpload
) {
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.log(
'[Sentry] Setting `sentry.sourceMapsUploadOptions.sourcemaps.filesToDeleteAfterUpload: [".*/**/public/**/*.map"]` to delete generated source maps after they were uploaded to Sentry.',
`[Sentry] Setting \`sentry.sourceMapsUploadOptions.sourcemaps.filesToDeleteAfterUpload: [${fallbackFilesToDelete
// Logging it as strings in the array
.map(path => `"${path}"`)
.join(', ')}]\` to delete generated source maps after they were uploaded to Sentry.`,
);
});
}
Expand Down Expand Up @@ -114,16 +191,16 @@ export function getPluginOptions(
ignore: sourceMapsUploadOptions.sourcemaps?.ignore ?? undefined,
filesToDeleteAfterUpload: sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload
? sourceMapsUploadOptions.sourcemaps?.filesToDeleteAfterUpload
: deleteFilesAfterUpload
? ['.*/**/public/**/*.map']
: shouldDeleteFilesFallback?.server || shouldDeleteFilesFallback?.client
? fallbackFilesToDelete
: undefined,
rewriteSources: (source: string) => normalizePath(source),
...moduleOptions?.unstable_sentryBundlerPluginOptions?.sourcemaps,
},
};
}

/* There are 3 ways to set up source maps (https://github.com/getsentry/sentry-javascript/issues/13993)
/* There are multiple ways to set up source maps (https://github.com/getsentry/sentry-javascript/issues/13993 and https://github.com/getsentry/sentry-javascript/pull/15859)
1. User explicitly disabled source maps
- keep this setting (emit a warning that errors won't be unminified in Sentry)
- We will not upload anything
Expand All @@ -133,11 +210,24 @@ export function getPluginOptions(
- we enable 'hidden' source maps generation
- configure `filesToDeleteAfterUpload` to delete all .map files (we emit a log about this)

Nuxt has 3 places to set source maps: vite options, rollup options, nuxt itself
Ideally, all 3 are enabled to get all source maps.
Users only have to explicitly enable client source maps. Sentry only overwrites the base Nuxt source map settings as they propagate.
*/

/** only exported for testing */
/** only exported for tests */
export function extractNuxtSourceMapSetting(
nuxt: { options: { sourcemap?: SourceMapSetting | { server?: SourceMapSetting; client?: SourceMapSetting } } },
runtime: 'client' | 'server' | undefined,
): SourceMapSetting | undefined {
if (!runtime) {
return undefined;
} else {
return typeof nuxt.options?.sourcemap === 'boolean' || typeof nuxt.options?.sourcemap === 'string'
? nuxt.options.sourcemap
: nuxt.options?.sourcemap?.[runtime];
}
}

/** only exported for testing */
export function changeNuxtSourceMapSettings(
nuxt: Nuxt,
sentryModuleOptions: SentryNuxtModuleOptions,
Expand All @@ -160,7 +250,7 @@ export function changeNuxtSourceMapSettings(

case 'hidden':
case true:
logKeepSourceMapSetting(sentryModuleOptions, 'sourcemap', (nuxtSourceMap as true).toString());
logKeepEnabledSourceMapSetting(sentryModuleOptions, 'sourcemap', (nuxtSourceMap as true).toString());
previousUserSourceMapSetting = { client: 'enabled', server: 'enabled' };
break;
case undefined:
Expand All @@ -175,7 +265,7 @@ export function changeNuxtSourceMapSettings(
warnExplicitlyDisabledSourceMap('sourcemap.client');
previousUserSourceMapSetting.client = 'disabled';
} else if (['hidden', true].includes(nuxtSourceMap.client)) {
logKeepSourceMapSetting(sentryModuleOptions, 'sourcemap.client', nuxtSourceMap.client.toString());
logKeepEnabledSourceMapSetting(sentryModuleOptions, 'sourcemap.client', nuxtSourceMap.client.toString());
previousUserSourceMapSetting.client = 'enabled';
} else {
nuxt.options.sourcemap.client = 'hidden';
Expand All @@ -187,7 +277,7 @@ export function changeNuxtSourceMapSettings(
warnExplicitlyDisabledSourceMap('sourcemap.server');
previousUserSourceMapSetting.server = 'disabled';
} else if (['hidden', true].includes(nuxtSourceMap.server)) {
logKeepSourceMapSetting(sentryModuleOptions, 'sourcemap.server', nuxtSourceMap.server.toString());
logKeepEnabledSourceMapSetting(sentryModuleOptions, 'sourcemap.server', nuxtSourceMap.server.toString());
previousUserSourceMapSetting.server = 'enabled';
} else {
nuxt.options.sourcemap.server = 'hidden';
Expand All @@ -199,74 +289,79 @@ export function changeNuxtSourceMapSettings(
return previousUserSourceMapSetting;
}

/** only exported for testing */
export function changeViteSourceMapSettings(
viteConfig: { build?: { sourcemap?: boolean | 'inline' | 'hidden' } },
/** Logs warnings about potentially conflicting source map settings.
* Configures `sourcemapExcludeSources` in Nitro to make source maps usable in Sentry.
*
* only exported for testing
*/
export function validateNitroSourceMapSettings(
nuxt: { options: { sourcemap?: SourceMapSetting | { server?: SourceMapSetting } } },
nitroConfig: NitroConfig,
sentryModuleOptions: SentryNuxtModuleOptions,
): UserSourceMapSetting {
viteConfig.build = viteConfig.build || {};
const viteSourceMap = viteConfig.build.sourcemap;

let previousUserSourceMapSetting: UserSourceMapSetting;

if (viteSourceMap === false) {
warnExplicitlyDisabledSourceMap('vite.build.sourcemap');
previousUserSourceMapSetting = 'disabled';
} else if (viteSourceMap && ['hidden', 'inline', true].includes(viteSourceMap)) {
logKeepSourceMapSetting(sentryModuleOptions, 'vite.build.sourcemap', viteSourceMap.toString());
previousUserSourceMapSetting = 'enabled';
} else {
viteConfig.build.sourcemap = 'hidden';
logSentryEnablesSourceMap('vite.build.sourcemap', 'hidden');
previousUserSourceMapSetting = 'unset';
}
): void {
const isDebug = sentryModuleOptions.debug;
const nuxtSourceMap = extractNuxtSourceMapSetting(nuxt, 'server');

return previousUserSourceMapSetting;
}
// NITRO CONFIG ---

validateDifferentSourceMapSettings({
nuxtSettingKey: 'sourcemap.server',
nuxtSettingValue: nuxtSourceMap,
otherSettingKey: 'nitro.sourceMap',
otherSettingValue: nitroConfig.sourceMap,
});

// ROLLUP CONFIG ---

/** only exported for testing */
export function changeRollupSourceMapSettings(
nitroConfig: {
rollupConfig?: {
output?: {
sourcemap?: OutputOptions['sourcemap'];
sourcemapExcludeSources?: OutputOptions['sourcemapExcludeSources'];
};
};
},
sentryModuleOptions: SentryNuxtModuleOptions,
): UserSourceMapSetting {
nitroConfig.rollupConfig = nitroConfig.rollupConfig || {};
nitroConfig.rollupConfig.output = nitroConfig.rollupConfig.output || { sourcemap: undefined };
const nitroRollupSourceMap = nitroConfig.rollupConfig.output.sourcemap;

let previousUserSourceMapSetting: UserSourceMapSetting;

const nitroSourceMap = nitroConfig.rollupConfig.output.sourcemap;
// We don't override nitro.rollupConfig.output.sourcemap (undefined by default, but overrides all other server-side source map settings)
if (typeof nitroRollupSourceMap !== 'undefined' && ['hidden', 'inline', true, false].includes(nitroRollupSourceMap)) {
const settingKey = 'nitro.rollupConfig.output.sourcemap';

if (nitroSourceMap === false) {
warnExplicitlyDisabledSourceMap('nitro.rollupConfig.output.sourcemap');
previousUserSourceMapSetting = 'disabled';
} else if (nitroSourceMap && ['hidden', 'inline', true].includes(nitroSourceMap)) {
logKeepSourceMapSetting(sentryModuleOptions, 'nitro.rollupConfig.output.sourcemap', nitroSourceMap.toString());
previousUserSourceMapSetting = 'enabled';
} else {
nitroConfig.rollupConfig.output.sourcemap = 'hidden';
logSentryEnablesSourceMap('nitro.rollupConfig.output.sourcemap', 'hidden');
previousUserSourceMapSetting = 'unset';
validateDifferentSourceMapSettings({
nuxtSettingKey: 'sourcemap.server',
nuxtSettingValue: nuxtSourceMap,
otherSettingKey: settingKey,
otherSettingValue: nitroRollupSourceMap,
});
}

nitroConfig.rollupConfig.output.sourcemapExcludeSources = false;
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.log(
'[Sentry] Disabled source map setting in the Nuxt config: `nitro.rollupConfig.output.sourcemapExcludeSources`. Source maps will include the actual code to be able to un-minify code snippets in Sentry.',
);
});
if (isDebug) {
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.log(
'[Sentry] Set `sourcemapExcludeSources: false` in the Nuxt config (`nitro.rollupConfig.output`). Source maps will now include the actual code to be able to un-minify code snippets in Sentry.',
);
});
}
}

return previousUserSourceMapSetting;
function validateDifferentSourceMapSettings({
nuxtSettingKey,
nuxtSettingValue,
otherSettingKey,
otherSettingValue,
}: {
nuxtSettingKey: string;
nuxtSettingValue?: SourceMapSetting;
otherSettingKey: string;
otherSettingValue?: SourceMapSetting;
}): void {
if (nuxtSettingValue !== otherSettingValue) {
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.warn(
`[Sentry] Source map generation settings are conflicting. Sentry uses \`${nuxtSettingKey}: ${nuxtSettingValue}\`. However, a conflicting setting was discovered (\`${otherSettingKey}: ${otherSettingValue}\`). This setting was probably explicitly set in your configuration. Sentry won't override this setting but it may affect source maps generation and upload. Without source maps, code snippets on the Sentry Issues page will remain minified.`,
);
});
}
}

function logKeepSourceMapSetting(
function logKeepEnabledSourceMapSetting(
sentryNuxtModuleOptions: SentryNuxtModuleOptions,
settingKey: string,
settingValue: string,
Expand All @@ -275,24 +370,24 @@ function logKeepSourceMapSetting(
consoleSandbox(() => {
// eslint-disable-next-line no-console
console.log(
`[Sentry] We discovered \`${settingKey}\` is set to \`${settingValue}\`. Sentry will keep this source map setting. This will un-minify the code snippet on the Sentry Issue page.`,
`[Sentry] We discovered \`${settingKey}\` is set to \`${settingValue}\`. This will un-minify the code snippet on the Sentry Issue page. Be aware that there might be other source map settings in your config which could overwrite this setting.`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

l: should we keep the "be aware" sentence here? as far as I understand, we'd emit an explicit warning anyway via validateDifferentSourceMapSettings, right?

The reason why I'm thinking about this is that this should be a "success message", right? I just want to convey this and not risk users thinking they did something wrong or mistake the message with a warning. Especially with "hidden" I could see users being confused.

What about something like this?

Suggested change
`[Sentry] We discovered \`${settingKey}\` is set to \`${settingValue}\`. This will un-minify the code snippet on the Sentry Issue page. Be aware that there might be other source map settings in your config which could overwrite this setting.`,
`[Sentry] \`${settingKey}\` is already set to \`${settingValue}\`. This will correctly un-minify the code snippet on the Sentry Issue page.`

Which brings me to an alternative question/idea: Do we even need this message at all? In case of users already having source maps enabled, there's nothing for us to do anyway, right? Not saying it has to go, just food for thought :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll change this to your suggestion but will keep it to show it when debug is enabled :)

);
});
}
}

function warnExplicitlyDisabledSourceMap(settingKey: string): void {
consoleSandbox(() => {
// eslint-disable-next-line no-console
// eslint-disable-next-line no-console
console.warn(
`[Sentry] Parts of source map generation are currently disabled in your Nuxt configuration (\`${settingKey}: false\`). This setting is either a default setting or was explicitly set in your configuration. Sentry won't override this setting. Without source maps, code snippets on the Sentry Issues page will remain minified. To show unminified code, enable source maps in \`${settingKey}\` (e.g. by setting them to \`hidden\`).`,
`[Sentry] We discovered \`${settingKey}\` is set to \`false\`. This setting is either a default setting or was explicitly set in your configuration. Sentry won't override this setting. Without source maps, code snippets on the Sentry Issues page will remain minified. To show unminified code, enable source maps in \`${settingKey}\` (e.g. by setting them to \`'hidden'\`).`,
);
});
}

function logSentryEnablesSourceMap(settingKey: string, settingValue: string): void {
consoleSandbox(() => {
// eslint-disable-next-line no-console
// eslint-disable-next-line no-console
console.log(`[Sentry] Enabled source map generation in the build options with \`${settingKey}: ${settingValue}\`.`);
});
}
Loading