docs: Add src dir limitation to slices and useStaticQuery (#37326)

gatsbyjs · Dec 23, 2022 · 250c8b7 · 250c8b7
1 parent 5498013
commit 250c8b7
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 0 deletions.
diff --git a/docs/docs/how-to/querying-data/use-static-query.md b/docs/docs/how-to/querying-data/use-static-query.md
@@ -92,3 +92,19 @@ Static queries thus have these limitations:
 
 - `useStaticQuery` does not accept variables (hence the name "static"), but can be used in _any_ component, including pages
 - Because of how queries currently work in Gatsby, Gatsby supports only a single instance of `useStaticQuery` in a file
+
+## Other limitations
+
+### Must be in `src` directory
+
+`useStaticQuery` must be used in files that are nested below your site's top-level `src` directory. For example:
+
+`useStaticQuery` works in these files:
+
+- `<SITE_ROOT>/src/my-page.js`
+- `<SITE_ROOT>/src/components/my-component.js`
+
+`useStaticQuery` **does not** work in these files:
+
+- `<SITE_ROOT>/other-components/other-component.js`
+- `<SITE_ROOT>/other-library/other-component.js`
diff --git a/docs/docs/reference/built-in-components/gatsby-slice.md b/docs/docs/reference/built-in-components/gatsby-slice.md
@@ -99,6 +99,20 @@ export const query = graphql`
 
 ## Restrictions on using `<Slice>` placeholder
 
+### Must be in `src` directory
+
+Slice placeholders must be used in files that are nested below your site's top-level `src` directory. For example:
+
+Slice placeholders work in these files:
+
+- `<SITE_ROOT>/src/my-page.js`
+- `<SITE_ROOT>/src/components/my-component.js`
+
+Slice placeholders **do not** work in these files:
+
+- `<SITE_ROOT>/other-components/other-component.js`
+- `<SITE_ROOT>/other-library/other-component.js`
+
 ### Nested Slices
 
 Gatsby does not support nested Slice placeholders. This means if you have a high level `<Layout>` component as a slice component, other Slice placeholders cannot exist within that `<Layout>` component anywhere in the tree.