feat: improve next.js experience (#3335)

packages/core/src/Controller/Controller.ts

@@ -208,6 +208,7 @@ export function Controller({ options }: StateServiceProps) {
     getTranslationNs: getTranslationNs,
     getDefaultAndFallbackNs: getDefaultAndFallbackNs,
     findPositions: pluginService.findPositions,
+    getRequiredRecords: getRequiredRecords,
     async changeLanguage(language: string) {
       if (
         state.getPendingLanguage() === language &&

packages/core/src/TolgeeCore.ts

@@ -127,6 +127,11 @@ function createTolgee(options: TolgeeOptions) {
      */
     isLoaded: controller.isLoaded,
 
+    /**
+     * Returns records needed for instance to be `loaded`
+     */
+    getRequiredRecords: controller.getRequiredRecords,
+
     /**
      * @return `true` if tolgee is loading initial data (triggered by `run`).
      */

packages/react/src/createServerInstance.tsx

@@ -20,7 +20,7 @@ export const createServerInstance = ({
     const tolgee = await createTolgee(locale);
     await tolgee.run();
     return tolgee;
-  });
+  }) as (locale: string) => Promise<TolgeeInstance>;
 
   const getTolgee = async () => {
     const locale = getLocale();

packages/react/src/useTolgeeSSR.ts

@@ -34,26 +34,44 @@ export function useTolgeeSSR(
   language?: string,
   staticData?: TolgeeStaticData | undefined
 ) {
-  const initialInstance = useMemo(
-    () => getTolgeeWithDeactivatedWrapper(tolgeeInstance),
-    []
+  const [noWrappingTolgee] = useState(() =>
+    getTolgeeWithDeactivatedWrapper(tolgeeInstance)
   );
 
-  const [tolgee, setTolgee] = useState(initialInstance);
+  const [initialRender, setInitialRender] = useState(true);
 
   useEffect(() => {
-    setTolgee(tolgeeInstance);
+    setInitialRender(false);
   }, []);
 
   useMemo(() => {
     // we have to prepare tolgee before rendering children
     // so translations are available right away
     // events emitting must be off, to not trigger re-render while rendering
-    tolgee.setEmitterActive(false);
-    tolgee.addStaticData(staticData);
-    tolgee.changeLanguage(language!);
-    tolgee.setEmitterActive(true);
-  }, [language, staticData, tolgee]);
+    tolgeeInstance.setEmitterActive(false);
+    tolgeeInstance.addStaticData(staticData);
+    tolgeeInstance.changeLanguage(language!);
+    tolgeeInstance.setEmitterActive(true);
+  }, [language, staticData, tolgeeInstance]);
 
-  return tolgee;
+  useState(() => {
+    // running this function only on first render
+    if (!tolgeeInstance.isLoaded()) {
+      // warning user, that static data provided are not sufficient
+      // for proper SSR render
+      const missingRecords = tolgeeInstance
+        .getRequiredRecords(language)
+        .map(({ namespace, language }) =>
+          namespace ? `${namespace}:${language}` : language
+        )
+        .filter((key) => !staticData?.[key]);
+
+      // eslint-disable-next-line no-console
+      console.warn(
+        `Tolgee: Missing records in "staticData" for proper SSR functionality: ${missingRecords.map((key) => `"${key}"`).join(', ')}`
+      );
+    }
+  });
+
+  return initialRender ? noWrappingTolgee : tolgeeInstance;
 }

packages/web/src/package/observers/general/ElementRegistry.ts

@@ -82,6 +82,7 @@ export function ElementRegistry(
   }
 
   return Object.freeze({
+    isRestricted: isRestricted,
     register(element: Element, node: Node, nodeMeta: NodeMeta) {
       if (isRestricted(element)) {
         return;

packages/web/src/package/observers/general/GeneralObserver.ts

@@ -54,7 +54,14 @@ export function GeneralObserver() {
 
     function handleNodes(nodes: Array<Text | Attr>) {
       for (const textNode of nodes) {
+        const parent = textNode.parentElement;
+
+        if (parent && elementRegistry.isRestricted(parent)) {
+          continue;
+        }
+
         const oldTextContent = getNodeText(textNode);
+
         const result = oldTextContent ? wrapper.unwrap(oldTextContent) : null;
         if (result) {
           const { text, keys } = result;

testapps/next-app/src/app/[locale]/layout.tsx

@@ -16,6 +16,8 @@ export default async function LocaleLayout({
     notFound();
   }
 
+  // it's important you provide all data which are needed for initial render
+  // so current locale and also fallback locales + necessary namespaces
   const locales = await getStaticData(['en', locale]);
 
   return (