Concerns with Nuqs v2 Adapter Pattern and a Potential Solution

[isBatak]

I've tried nuqs v2 and noticed the introduction of the Adapter pattern, which adds an <NuqsAdapter> component at the root of the application. While I understand the purpose behind it, I have concerns regarding its long-term impact on bundle size and web optimization, especially for web-based applications.

Problem with the Adapter Pattern

Currently, the Adapter component is bundled with every page of the app, even if the page doesn't leverage the functionality of useQueryState or any nuqs library features. The overhead might be negligible, but as time passes, this pattern might cause unnecessary bloat in the bundle, particularly if the adapter's internal logic grows.
Web performance is a key concern, and we want to minimize the amount of JavaScript shipped to the client, especially when certain pages don't require those features.

Proposed Solution: Framework-Specific Submodules

Instead of using a monolithic Adapter that gets bundled with every page, I propose a framework-specific submodule approach. This would involve creating different builds for different frameworks (e.g., Next.js, Remix) and only importing what’s necessary based on the target framework. This way, we keep a single codebase but split it into multiple build targets that optimize for specific platforms.

Example Setup:

You could structure the Nuqs library to export specific modules for each target environment.

Example of Build Targets:

• nuqs/next: Optimized for Next.js
• nuqs/remix: Optimized for Remix

Using a build system like Tsup, you can set up conditional builds for each framework.

tsup.config.ts example:

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  sourcemap: true,
  minify: true,
  external: ['react', 'react-dom'],
  platform: 'browser',
  define: {
    'process.env.FRAMEWORK_TARGET': JSON.stringify(process.env.FRAMEWORK_TARGET || ''),
  },
});

Example index.ts with Static Imports

// src/index.ts

// Only load the correct module based on the build-time environment variable
// This ensures the unused branch gets tree-shaken away

if (process.env.FRAMEWORK_TARGET === 'nextjs') {
  // Use static imports for Next.js
  import { default as frameworkSpecificModule } from './next-specific-module';
  frameworkSpecificModule();
} else if (process.env.FRAMEWORK_TARGET === 'remix') {
  // Use static imports for Remix
  import { default as frameworkSpecificModule } from './remix-specific-module';
  frameworkSpecificModule();
}

You could then use framework-specific imports like so:

import { useQueryState } from 'nuqs/next';  // For Next.js
// or
import { useQueryState } from 'nuqs/remix'; // For Remix

Build and Test Dead Code Elimination

When you run the build, Tsup will inject the FRAMEWORK_TARGET as a static value in the code, and the bundler will remove the unused branch, ensuring that only the target-specific code remains in the bundle.

For example:

• When you run FRAMEWORK_TARGET=nextjs tsup, the conditional if (process.env.FRAMEWORK_TARGET === 'remix') will be removed, and only the Next.js code will be retained in the final bundle.
• When you run FRAMEWORK_TARGET=remix tsup, the conditional if (process.env.FRAMEWORK_TARGET === 'nextjs') will be eliminated.

This would ensure that only the relevant code for each framework is included in the bundle, avoiding unnecessary Adapter overhead in pages that don’t need it.

Benefits:

• Avoids Global Adapter Pattern: No need to wrap the entire app with an Adapter component.
• Collocates Adapter Logic: The adapter logic is included only where it’s needed, inside framework-specific hooks like useQueryState.
• Smaller Bundle Size: Only framework-relevant code gets included, reducing bundle bloat.
• Future-Proof: As more functionality gets added, this approach can help manage code growth without impacting performance across the entire application.
• Modular: Developers can import the features they need based on the framework, keeping the bundle lean and performant.

I believe this could provide a more scalable solution, especially as Nuqs continues to evolve.

[franky47]

Thanks for your feedback.

The adapters are already code-split on framework internals. For example: if you're using Remix, there's nothing related to Next.js imported in your bundle when you import from nuqs/adapter/remix.

nuqs/packages/nuqs/tsup.config.ts

Lines 19 to 26 in c96f238

	'adapters/react': 'src/adapters/react.ts',
	'adapters/next': 'src/adapters/next.ts',
	'adapters/next/app': 'src/adapters/next/app.ts',
	'adapters/next/pages': 'src/adapters/next/pages.ts',
	'adapters/remix': 'src/adapters/remix.ts',
	'adapters/react-router': 'src/adapters/react-router.ts',
	'adapters/custom': 'src/adapters/custom.ts',
	'adapters/testing': 'src/adapters/testing.ts'

The core (hooks, parsers, serializer etc, everything you import from nuqs and nuqs/server) are framework-agnostic. The only core peer dependency is React.

Note that in 2.0.1 we fixed an issue where all the optionalDependencies (next, react-router-dom, @remix-run/react) were downloaded and installed by package managers. This did have an impact not on bundle size, but on node_modules size.

I see the point about not wanting to bundle the <NuqsAdapter> into every single page. The docs show you how to place it as high in the tree as possible, for an easy start and low cognitive overhead, but it's absolutely possible to place it lower in the tree, closer to where it's used, and have multiple siblings or cousins of each other in the tree:

<RootLayout>
  <LayoutA>
    <NuqsAdapter>
     <PageA/>
    </NuqsAdapter>
  </LayoutA>
  <LayoutB>
    <NuqsAdapter>
     <PageB/>
    </NuqsAdapter>
  </LayoutB>
</RootLayout>

The suggestion of importing core features from framework-specific imports was already discarded when we supported only Next.js app & pages routers, to avoid writing components that are locked to a particular framework.

The idea with v2's compatibility with other frameworks is to keep components that use nuqs universal across supported frameworks, so they can be shared freely within the React community. The adapters are here to finish the job of integrating those components to a particular framework.

[isBatak]

As you mentioned, moving the adapter lower in the tree is a possible solution, but it comes with the tradeoff of increased cognitive overhead for developers. Now, users have to remember whether useQueryState are still in use within the sub-tree and, if not, manually remove the NuqsAdapter accordingly. This process is cumbersome and could inadvertently lead to even more bundle size issues if not managed carefully.

My suggestion aims to shift this responsibility from user-land to library-land. Instead of relying on the user to manually optimize where and how adapters are placed, you can handle this at the library's build time. You can still keep the adapters in the codebase, but the optimization and conditional loading would happen during the build process, similar to how React Native uses the Platform.select API https://reactnative.dev/docs/platform-specific-code.

For example:

const Component = Platform.select({
  ios: () => require('ComponentIOS'),
  android: () => require('ComponentAndroid'),
})();

<Component />;

This would allow developers to import and use framework-specific packages, bundling only the code required for that particular framework (e.g., Next.js, Remix). From the library maintenance side, you would still have one codebase, but the build output would generate framework-specific artifacts. This way, you get the best of both worlds: reduced cognitive overload for developers and efficient bundle sizes, while keeping the codebase maintainable.

Of course, this is just my perspective, and I’m sharing these ideas to explore potential improvements.