Using Object.defineProperty on a class field does not work as expected in my NextJS project (but it works just fine in a NodeJS program)

[chrismiddle10]

Summary

I created my Next.js 16.0.10 (Turbopack) project using npx create-next-app@latest with the following options:

Would you like to use TypeScript? Yes
Which linter would you like to use? ESLint
Would you like to use React Compiler? No
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the import alias (`@/*` by default)? No

The below is a very simple example of the issue I am having. I am simply trying to override the class-defined myPublicField field using Object.defineProperty.

class MyClass {
    protected _myProtectedField: string;
    public myPublicField: string;

    public toJSON() {
        return {
            myPublicField: this.myPublicField,
        };
    }
}

Object.defineProperty( MyClass.prototype, 'myPublicField', {
    configurable: true,
    enumerable: true,
    get() {
        return this._myProtectedField;
    },
    set( value: string ) {
        this._myProtectedField = typeof value === 'string' ? value.toUpperCase() : value;
    },
} );

const data = new MyClass();
data.myPublicField = 'hello world';

console.log( JSON.stringify( data ) );

NodeJS (expected results)

{"myPublicField":"HELLO WORLD"}

NextJS

{"myPublicField":"hello world"}

In all of my code, outside NextJS, this works as expected. Bringing this pattern into a NextJS project causes the failure. I can get it to work in NextJS if I apply the Object.defineProperty override to an instance of the class, but for whatever reason, it does not work when I apply it to the class prototype.

I assume that this is an issue related to some TypeScript or NextJS config, but I am not sure.

THIS WAS TAKEN FROM A FILE IN MY NEXTJS PROJECT AT /api/instance/route.ts

class MyClass {
    protected _myProtectedField: string;
    public myPublicField: string;

    public toJSON() {
        return {
            myPublicField: this.myPublicField,
        };
    }
}

export function GET( _request: Request ): Response {
    const data = new MyClass();

    Object.defineProperty( data, 'myPublicField', {
        configurable: true,
        enumerable: true,
        get() {
            return this._myProtectedField;
        },
        set( value: string ) {
            this._myProtectedField = typeof value === 'string' ? value.toUpperCase() : value;
        },
    } );

    data.myPublicField = 'hello world';
    return Response.json( data );
}

// This works as expected, but I do not want to have to apply the field override to every single class instance.
Response: {"myPublicField":"HELLO WORLD"} 

THIS WAS TAKEN FROM A FILE IN MY NEXTJS PROJECT AT /api/prototype/route.ts

class MyClass {
    protected _myProtectedField: string;
    public myPublicField: string;

    public toJSON() {
        return {
            myPublicField: this.myPublicField,
        };
    }
}

Object.defineProperty( MyClass.prototype, 'myPublicField', {
    configurable: true,
    enumerable: true,
    get() {
        return this._myProtectedField;
    },
    set( value: string ) {
        this._myProtectedField = typeof value === 'string' ? value.toUpperCase() : value;
    },
} );

export function GET( _request: Request ): Response {
    const data = new MyClass();
    data.myPublicField = 'hello world';

    return Response.json( data );
}

// I expect this to have uppercased HELLO WORLD, but it does not.
Response: {"myPublicField":"hello world"}

Additional information

No response

Example

No response

[tt-a1i]

This behavior is caused by TypeScript's useDefineForClassFields setting, which is enabled by default in Next.js (because it targets ES2022+).

What's happening:

When useDefineForClassFields: true, TypeScript compiles class fields using Object.defineProperty directly on the instance in the constructor:

// Your TypeScript
class MyClass {
  public myPublicField: string;
}

// Compiled JavaScript (with useDefineForClassFields: true)
class MyClass {
  constructor() {
    Object.defineProperty(this, "myPublicField", {
      enumerable: true,
      configurable: true,
      writable: true,
      value: void 0
    });
  }
}

This instance property shadows your prototype property, which is why defineProperty on the prototype doesn't work - the instance property takes precedence.

Solutions:

1. Use declare keyword (recommended):

class MyClass {
  protected _myProtectedField: string;
  declare public myPublicField: string; // <-- declare prevents emission
}

2. Disable useDefineForClassFields in tsconfig.json:

{
  "compilerOptions": {
    "useDefineForClassFields": false
  }
}

(Note: this might have other side effects with your target/libs)

3. Use a getter/setter in the class directly:

class MyClass {
  protected _myProtectedField: string;
  
  get myPublicField(): string {
    return this._myProtectedField;
  }
  
  set myPublicField(value: string) {
    this._myProtectedField = typeof value === 'string' ? value.toUpperCase() : value;
  }
}

The declare approach is cleanest if you need the prototype pattern for inheritance or other reasons.

[icyJoseph]

As the other comment says, this is caused by TS compile output:

• useDefineForClassFields: false ~ playground
• useDefineForClassFields: true or target set to 2022 or higher ~ playground

The one takeaway though, https://www.typescriptlang.org/tsconfig/#useDefineForClassFields:

This flag is used as part of migrating to the upcoming standard version of class fields. TypeScript introduced class fields many years before it was ratified in TC39. The latest version of the upcoming specification has a different runtime behavior to TypeScript’s implementation but the same syntax.

This flag switches to the upcoming ECMA runtime behavior.

So, what you observe when using it in Next.js is what the behavior will be, eventually... from MDN, https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields:

Because class fields are added using the [[DefineOwnProperty]] semantic (which is essentially Object.defineProperty()), field declarations in derived classes do not invoke setters in the base class. This behavior differs from using this.field = … in the constructor.

Note: Before the class fields specification was finalized with the [[DefineOwnProperty]] semantic, most transpilers, including Babel and tsc, transformed class fields to the DerivedWithConstructor form, which has caused subtle bugs after class fields were standardized.

I think the get/set approach:

  public get myPublicField(): string {
    return this._myProtectedField;
  }

  public set myPublicField(value: string) {
    this._myProtectedField = value.toUpperCase();
  }

Is the right approach here. Though just like the declare approach (which doesn't really create any runtime property, just TS level info) - both approaches could be not doable if your target Class is outside of your control 🤔 so then, you could either extend the source class, maybe even need to do some aliasing in your tsconfig.json, so that you have a file where you extend and export everything again, so that you don't have to modify your code downstream.

[chrismiddle10]

Thank you, @tt-a1i and @icyJoseph, for responding with this great information. Using the declare keyword will work well for my purposes, which involves decorators and some generated code in the affected getters/setters.

I will say that I generated a new project and added the "useDefineForClassFields": false option to the tsconfig.json. Simply setting this config did not produce the desired results. Can you comment on this? (Personally, I am not terribly concerned now that I understand the root-cause, but it might be worth it while this discussion is still active.)

Thanks again!

[icyJoseph]

Feels like the value description https://www.typescriptlang.org/tsconfig/#useDefineForClassFields is not that clear:

true if target is ES2022 or higher, including ESNext; false otherwise.

Perhaps it means that if the target is ES2022, then it is locked in place to true? Cuz it has to? to be compliant?

[chrismiddle10]

I was thinking along those lines based on what was said earlier: "This behavior is caused by TypeScript's useDefineForClassFields setting, which is enabled by default in Next.js (because it targets ES2022+)."

So, basically, when using NextJS, useDefineForClassFields is locked into true, and I am fine with that. I just wanted to do a quick follow-up. Thanks!