dart
flutter-freezed

Dart Flutter Freezed Classes

Package nameWeekly DownloadsVersionLicenseUpdated
@graphql-codegen/flutter-freezedDownloadsVersionLicenseSep 5th, 2024

Installation

npm i -D @graphql-codegen/flutter-freezed

configure the flutter-freezed plugin

Config API Reference

camelCasedEnums

type: {(boolean | DartIdentifierCasing)} default: true

Setting this option to true will camelCase enum values as required by Dart’s recommended linter.

If set to false, the original casing as specified in the Graphql Schema is used

You can also transform the casing by specifying your preferred casing for Enum values.

Available options are: 'snake_case', 'camelCase' and 'PascalCase'

For consistency, this option applies the same configuration to all Enum Types in the GraphQL Schema

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          camelCasedEnums: true, // or false
          // OR: specify a DartIdentifierCasing
          camelCasedEnums: 'snake_case',
        },
      },
    },
  },
};
export default config;

copyWith

type: {(boolean | TypeNamePattern)} default: undefined

The freezed library has this option enabled by default. Use this option to enable/disable this option completely.

The plugin by default generates immutable Freezed models using the @freezed decorator.

If this option is configured, the plugin will generate immutable Freezed models using the @Freezed(copyWith: value) instead.

Setting a boolean value will enable/disable this option globally for every GraphQL Type but you can also set this option to true for one or more GraphQL Types using a TypeNamePattern.

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Droid = TypeName.fromString('Droid');
const Starship = TypeName.fromString('Starship');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          copyWith: true,
          // OR: enable it for only Droid and Starship GraphQL types
          copyWith: TypeNamePattern.forTypeNames([Droid, Starship]),
        },
      },
    },
  },
};
export default config;

customScalars

type: {(Record<string, string>)} default: [object Object]

The key is the GraphQL Scalar Type and the value is the equivalent Dart Type

The plugin automatically handles built-in GraphQL Scalar Types so only specify the custom Scalars in your Graphql Schema.

Usage Examples

Usage
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          customScalars: {
            jsonb: 'Map<String, dynamic>',
            timestamp: 'DateTime',
            UUID: 'String',
          },
        },
      },
    },
  },
};
export default config;

defaultValues

type: {([pattern: FieldNamePattern, value: string, appliesOn: AppliesOnParameters[]][])} default: undefined

This will annotate the generated parameter with a @Default(value: defaultValue) decorator.

The default value will be interpolated into the @Default(value: ${value}) decorator so Use backticks for the value element so that you can use quotation marks for string values. E.g: "I'm a string default value" but Episode.jedi is not a string value.

Use the appliesOn to specify where this option should be applied on

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const MovieCharacter = TypeName.fromString('MovieCharacter');
const appearsIn = FieldName.fromString('appearsIn');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          defaultValues: [
            [FieldNamePattern.forFieldNamesOfTypeName(MovieCharacter, appearsIn), `Episode.jedi`, ['default_factory_parameter']],
          ],
        },
      },
    },
  },
};
export default config;

deprecated

type: {([pattern: Pattern, appliesOn: (AppliesOnFactory | AppliesOnParameters)[]][])} default: undefined

Using a TypeNamePattern, you can mark an entire factory constructor for one or more GraphQL types as deprecated.

Likewise, using a FieldNamePattern, you can mark one or more fields as deprecated

Since the first element in the tuple has a type signature of Pattern, you can use either TypeNamePattern or FieldNamePattern or use both by composing them with Pattern.compose(...)

Use the appliesOn to specify which block this option should be applied on

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const MovieCharacter = TypeName.fromString('MovieCharacter');
const Droid = TypeName.fromString('Droid');
const Starship = TypeName.fromString('Starship');
const Human = TypeName.fromString('Human');
 
const name = FieldName.fromString('name');
const appearsIn = FieldName.fromString('appearsIn');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          deprecated: [
            // using FieldNamePattern
            [FieldNamePattern.forFieldNamesOfTypeName(MovieCharacter, [appearsIn, name]), ['default_factory_parameter']],
            // using TypeNamePattern
            [TypeNamePattern.forTypeNames([Starship,Droid,Human]), ['union_factory']],
          ],
        },
      },
    },
  },
};
export default config;

equal

type: {(boolean | TypeNamePattern)} default: undefined

The freezed library has this option enabled by default. Use this option to enable/disable this option completely.

The plugin by default generates immutable Freezed models using the @freezed decorator.

If this option is configured, the plugin will generate immutable Freezed models using the @Freezed(equal: value) instead.

Setting a boolean value will enable/disable this option globally for every GraphQL Type but you can also set this option to true for one or more GraphQL Types using a TypeNamePattern.

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Droid = TypeName.fromString('Droid');
const Starship = TypeName.fromString('Starship');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          equal: true,
          // OR: enable it for only Droid and Starship GraphQL types
          equal: TypeNamePattern.forTypeNames([Droid, Starship]),
        },
      },
    },
  },
};
export default config;

escapeDartKeywords

type: {(boolean | [pattern: Pattern, prefix?: string, suffix?: string, appliesOn?: AppliesOn[]][])} default: true

Wraps the fields names that are valid Dart keywords with the prefix and suffix given

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Episode = TypeName.fromString('Episode');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          // WARNING: Setting this option to `false` might generate output that contains Dart keywords as identifiers. Defaults to `true`
          escapeDartKeywords: false,
          // OR configure how Dart keywords are handled for each type
          escapeDartKeywords: [
            [
              Pattern.compose([
                TypeNamePattern.forAllTypeNames(),
                FieldNamePattern.forAllFieldNamesOfTypeName([Episode]),
              ]),
              // `prefix`: defaults to an empty string `''` if undefined.
              // WARNING: Note that using a underscore `_` as a prefix will make the field as private
              undefined,
              // `suffix`: defaults to an underscore `_` if undefined
              undefined,
              // `appliesOn`: defaults to an ['enum', 'enum_value', 'class', 'factory', 'parameter'] if undefined.
              undefined,
            ],
          ],
        },
      },
    },
  },
};
export default config;

final

type: {([pattern: FieldNamePattern, appliesOn: AppliesOnParameters[]][])} default: undefined

This will mark the specified parameters as final

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const id = FieldName.fromString('id');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          final: [[FieldNamePattern.forFieldNamesOfAllTypeNames([id]), ['parameter']]],
        },
      },
    },
  },
};
export default config;

ignoreTypes

type: {(TypeNamePattern)} default: undefined

names of GraphQL types to ignore when generating Freezed classes

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const PaginatorInfo = TypeName.fromString('PaginatorInfo');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          ignoreTypes: TypeNamePattern.forTypeNames([PaginatorInfo]),
        },
      },
    },
  },
};
export default config;

immutable

type: {(boolean | TypeNamePattern)} default: undefined

The freezed library by default generates immutable models decorated with the @freezed decorator. This option if set to false the plugin will generate mutable Freezed models using the @unfreezed decorator instead.

Setting a boolean value will enable/disable this option globally for every GraphQL Type but you can also set this option to true for one or more GraphQL Types using a TypeNamePattern.

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Droid = TypeName.fromString('Droid');
const Starship = TypeName.fromString('Starship');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          immutable: true,
          // OR: enable it for all GraphQL types except Droid and Starship types
          immutable: TypeNamePattern.forTypeNamesExcludeTypeNames([Droid, Starship]),
        },
      },
    },
  },
};
export default config;

makeCollectionsUnmodifiable

type: {(boolean | TypeNamePattern)} default: undefined

allows collections(lists/maps) to be modified even if class is immutable

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Droid = TypeName.fromString('Droid');
const Starship = TypeName.fromString('Starship');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          makeCollectionsUnmodifiable: true,
          // OR: enable it for only Droid and Starship GraphQL types
          makeCollectionsUnmodifiable: TypeNamePattern.forTypeNames([Droid, Starship]),
        },
      },
    },
  },
};
export default config;

mergeTypes

type: {(Record<string, TypeName[]>)} default: undefined

maps over the value(array of typeNames) and transform each as a named factory constructor inside a class generated for the key(target GraphQL Object Type).

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Movie = TypeName.fromString('Movie');
const CreateMovieInput = TypeName.fromString('CreateMovieInput');
const UpdateMovieInput = TypeName.fromString('UpdateMovieInput');
const UpsertMovieInput = TypeName.fromString('UpsertMovieInput');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
         mergeTypes: {
           [Movie.value]: [CreateMovieInput, UpdateMovieInput, UpsertMovieInput],
         },
        },
      },
    },
  },
};
export default config;

mutableInputs

type: TypeNamePattern | boolean default: true

since inputs will be used to collect data, it makes sense to make them mutable with Freezed’s @unfreezed decorator.

This overrides(in order words: has a higher precedence than) the immutable config value ONLY for GraphQL input types.

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const CreateMovieInput = TypeName.fromString('CreateMovieInput');
const UpdateMovieInput = TypeName.fromString('UpdateMovieInput');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          mutableInputs: true,
          // OR: enable it for only Droid and Starship GraphQL types
          mutableInputs: TypeNamePattern.forTypeNames([CreateMovieInput, UpdateMovieInput]),
        },
      },
    },
  },
};
export default config;

privateEmptyConstructor

type: TypeNamePattern | boolean default: true

if true, defines a private empty constructor to allow getter and methods to work on the class

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const Droid = TypeName.fromString('Droid');
const Starship = TypeName.fromString('Starship');
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          privateEmptyConstructor: true,
          // OR: enable it for only Droid and Starship GraphQL types
          privateEmptyConstructor: TypeNamePattern.forTypeNames([Droid, Starship]),
        },
      },
    },
  },
};
export default config;

unionClass

type: [][] default: undefined

customize the key to be used for fromJson with multiple constructors

Usage Examples

Usage:
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  // ...
  generates: {
    'lib/data/models/app_models.dart': {
      plugins: {
        'flutter-freezed': {
          // ...
          unionClass: [
            [
              'SearchResult', // <-- unionTypeName
              'namedConstructor', // <-- unionKey
              'FreezedUnionCase.pascal', // <-- unionValueCase
              [ // <-- unionValuesNameMap
               [ Droid, 'special droid'],
               [ Human, 'astronaut'],
               [ Starship, 'space_Shuttle'],
              ],
            ],
          ],
        },
      },
    },
  },
};
export default config;

The flutter-freezed plugin generates [Freezed] models using a GraphQL Schema.

Please refer the Flutter Freezed Guide for how to get started with this plugin.