diff --git a/website/docs/guides/alias-directive.md b/website/docs/guides/alias-directive.md index 6749480cfdac7..3624fa480560b 100644 --- a/website/docs/guides/alias-directive.md +++ b/website/docs/guides/alias-directive.md @@ -105,7 +105,8 @@ We've outlined two different ways that fragments can be unsafe in Relay today wi To experiment with this validation in your project today, you can enable the experimental `enforce_fragment_alias_where_ambiguous` compiler feature flag for your project. To enable incremental adoption of this enforcement, Relay exposes a directive `@dangerously_unaliased_fixme` which will suppress these enforcement errors. This will allow you to enable the enforcement for all new spreads without first needing to migrate all existing issues. -The [Relay VSCode extension](../editor-support.md) offers quick fixes to add either `@alias` or `@dangerously_unaliased_fixme` to unsafe fragments. +The [Relay VSCode extension](../editor-support.md) offers quick fixes to add either `@alias` or `@dangerously_unaliased_fixme` to unsafe fragments, and the +[mark-dangerous-conditional-fragment-spreads](../codemods/#mark-dangerous-conditional-fragment-spreads) codemod can be used to apply `@dangerously_unaliased_fixme` across your entire project. ## Use with @required diff --git a/website/docs/guides/codemods.md b/website/docs/guides/codemods.md new file mode 100644 index 0000000000000..5eabf47a3ad6d --- /dev/null +++ b/website/docs/guides/codemods.md @@ -0,0 +1,57 @@ +--- +id: codemods +title: Codemods +slug: /guides/codemods/ +description: Relay guide to codemods +keywords: + - codemod + - codemods +--- + +import DocsRating from '@site/src/core/DocsRating'; import {FbInternalOnly, +OssOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal'; import +Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + +The Relay compiler has the ability to make changes across the source files of +your projects with the use of codemods. You can see the list of codemods +available by running the Relay compiler's `codemod` command: + +``` +> relay codemod --help +Apply codemod (verification with auto-applied fixes) + +Usage: relay codemod [OPTIONS] [CONFIG] + +Commands: + mark-dangerous-conditional-fragment-spreads Marks unaliased conditional fragment spreads as @dangerously_unaliased_fixme + help Print this message or the help of the given subcommand(s) + +Arguments: + [CONFIG] Compile using this config file. If not provided, searches for a config in package.json under the `relay` key or `relay.config.json` files among other up from the current working directory + +Options: + -p, --project Compile only this project. You can pass this argument multiple times. to compile multiple projects. If excluded, all projects will be compiled + -h, --help Print help +``` + +## Available codemods + +The compiler currently has one available codemod: + +### mark-dangerous-conditional-fragment-spreads + +This codemod finds fragment spreads that are _dangerously unaliased_; that is, +the fragment might not be fetched due to a directive such as `@skip` or its +inclusion on a mismatched type within a union. If such a conditional fragment is +not aliased with [`@alias`](../alias-directive/), there is no way for the +resulting generated Flow or TypeScript types to reflect its nullability. This +codemod will add the `@dangerously_unaliased_fixme` directive to such fragment +spreads, indicating to developers that there is a problem to be fixed. After +applying this codemod, the `enforce_fragment_alias_where_ambiguous` feature flag +can be enabled, which will ensure any future ambiguous fragment spreads must be +aliased. + +Since this codemod can potentially modify many files, there is an optional +`--rollout` parameter which, if used alongside the +`enforce_fragment_alias_where_ambiguous` feature flag in rollout mode, allows +progressive codemod and enforcement of this validation. diff --git a/website/sidebars.js b/website/sidebars.js index c77a088fdc973..487b9d624c634 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -135,6 +135,7 @@ const Guides = { }), 'guides/type-emission', ], + Codemods: ['guides/codemods'], // TODO(T84797602) release incremental data delivery externally // 'guides/incremental-data-delivery', // TODO release these in OSS