[{"data":1,"prerenderedAt":750},["ShallowReactive",2],{"navigation_docs":3,"-advanced":38,"-advanced-surround":745},[4,30,34],{"title":5,"path":6,"stem":7,"children":8,"page":29},"Getting Started","\u002Fget-started","1.get-started",[9,13,17,21,25],{"title":10,"path":11,"stem":12},"Installation","\u002Fget-started\u002Finstallation","1.get-started\u002F1.installation",{"title":14,"path":15,"stem":16},"Configuration","\u002Fget-started\u002Fconfiguration","1.get-started\u002F2.configuration",{"title":18,"path":19,"stem":20},"Usage","\u002Fget-started\u002Fusage","1.get-started\u002F3.usage",{"title":22,"path":23,"stem":24},"Providers","\u002Fget-started\u002Fproviders","1.get-started\u002F4.providers",{"title":26,"path":27,"stem":28},"Upgrade Guide","\u002Fget-started\u002Fupgrade","1.get-started\u002F5.upgrade",false,{"title":31,"path":32,"stem":33},"Advanced","\u002Fadvanced","2.advanced",{"title":35,"path":36,"stem":37},"Contributing","\u002Fcontributing","3.contributing",{"id":39,"title":31,"body":40,"description":738,"extension":739,"links":740,"meta":741,"navigation":742,"path":32,"seo":743,"stem":33,"__hash__":744},"docs\u002F2.advanced.md",{"type":41,"value":42,"toc":730},"minimark",[43,48,57,428,432,439,498,501,558,571,575,578,585,588,667,673,676,726],[44,45,47],"h2",{"id":46},"how-it-works","How it works",[49,50,51,52,56],"p",{},"Nuxt Fonts processes all your CSS and does the following things automatically when it encounters a ",[53,54,55],"code",{},"font-family"," declaration.",[58,59,60,99,333,343,422],"ol",{},[61,62,63,67,68,71,72,75,76,79,80,75,83,86,87,90,91,98],"li",{},[64,65,66],"strong",{},"Resolves fonts used in CSS",". It starts by looking in your ",[53,69,70],{},"public\u002F"," directory for font files that match the name, like ",[53,73,74],{},"Roboto.woff2",", ",[53,77,78],{},"RobotoBold.ttf",", etc. Then it moves on to web font providers like ",[53,81,82],{},"google",[53,84,85],{},"bunny"," and ",[53,88,89],{},"fontshare",". Once a provider is found (in this case, probably ",[92,93,97],"a",{"href":94,"rel":95},"https:\u002F\u002Ffonts.google.com",[96],"nofollow","Google Fonts","), we move on to the next step.",[61,100,101,108,109,111,112,166],{},[64,102,103,104,107],{},"Generates and injects ",[53,105,106],{},"@font-face"," rules for you."," We'll generate rules to point your browser to the right source files. They'll be injected into the same CSS where you use the ",[53,110,55],{},".",[113,114,119],"pre",{"className":115,"code":116,"language":117,"meta":118,"style":118},"language-css shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","\u002F* If you write something like this: *\u002F\n:root {\n  font-family: Poppins;\n}\n","css","",[53,120,121,130,144,160],{"__ignoreMap":118},[122,123,126],"span",{"class":124,"line":125},"line",1,[122,127,129],{"class":128},"sHwdD","\u002F* If you write something like this: *\u002F\n",[122,131,133,137,141],{"class":124,"line":132},2,[122,134,136],{"class":135},"sMK4o",":",[122,138,140],{"class":139},"spNyl","root",[122,142,143],{"class":135}," {\n",[122,145,147,151,153,157],{"class":124,"line":146},3,[122,148,150],{"class":149},"sqsOY","  font-family",[122,152,136],{"class":135},[122,154,156],{"class":155},"sTEyZ"," Poppins",[122,158,159],{"class":135},";\n",[122,161,163],{"class":124,"line":162},4,[122,164,165],{"class":135},"}\n",[113,167,169],{"className":115,"code":168,"language":117,"meta":118,"style":118},"\u002F* Then Nuxt fonts will add declarations that look like this at the beginning of the CSS file: *\u002F\n@font-face {\n  font-family: 'Poppins';\n  src: local(\"Poppins\"), url(\"\u002F_fonts\u002F\u003Chash>.woff2\") format(woff2);\n  font-display: swap;\n  unicode-range: U+0000-00FF,U+0131, \u002F* ... *\u002F;\n  font-weight: 400;\n  font-style: normal;\n}\n\u002F* ... plus more font-face declarations for other unicode ranges\u002Fweights *\u002F\n",[53,170,171,176,183,201,252,265,295,309,322,327],{"__ignoreMap":118},[122,172,173],{"class":124,"line":125},[122,174,175],{"class":128},"\u002F* Then Nuxt fonts will add declarations that look like this at the beginning of the CSS file: *\u002F\n",[122,177,178,181],{"class":124,"line":132},[122,179,106],{"class":180},"s7zQu",[122,182,143],{"class":135},[122,184,185,187,189,192,196,199],{"class":124,"line":146},[122,186,150],{"class":149},[122,188,136],{"class":135},[122,190,191],{"class":135}," '",[122,193,195],{"class":194},"sfazB","Poppins",[122,197,198],{"class":135},"'",[122,200,159],{"class":135},[122,202,203,206,208,212,215,218,220,222,225,228,230,232,235,237,240,243,245,249],{"class":124,"line":162},[122,204,205],{"class":149},"  src",[122,207,136],{"class":135},[122,209,211],{"class":210},"s2Zo4"," local",[122,213,214],{"class":135},"(",[122,216,217],{"class":135},"\"",[122,219,195],{"class":194},[122,221,217],{"class":135},[122,223,224],{"class":135},"),",[122,226,227],{"class":210}," url",[122,229,214],{"class":135},[122,231,217],{"class":135},[122,233,234],{"class":194},"\u002F_fonts\u002F\u003Chash>.woff2",[122,236,217],{"class":135},[122,238,239],{"class":135},")",[122,241,242],{"class":210}," format",[122,244,214],{"class":135},[122,246,248],{"class":247},"sHdIc","woff2",[122,250,251],{"class":135},");\n",[122,253,255,258,260,263],{"class":124,"line":254},5,[122,256,257],{"class":149},"  font-display",[122,259,136],{"class":135},[122,261,262],{"class":155}," swap",[122,264,159],{"class":135},[122,266,268,271,273,276,279,282,285,288,290,293],{"class":124,"line":267},6,[122,269,270],{"class":149},"  unicode-range",[122,272,136],{"class":135},[122,274,275],{"class":155}," U+0000",[122,277,278],{"class":135},"-",[122,280,281],{"class":155},"00FF",[122,283,284],{"class":135},",",[122,286,287],{"class":155},"U+0131",[122,289,284],{"class":135},[122,291,292],{"class":128}," \u002F* ... *\u002F",[122,294,159],{"class":135},[122,296,298,301,303,307],{"class":124,"line":297},7,[122,299,300],{"class":149},"  font-weight",[122,302,136],{"class":135},[122,304,306],{"class":305},"sbssI"," 400",[122,308,159],{"class":135},[122,310,312,315,317,320],{"class":124,"line":311},8,[122,313,314],{"class":149},"  font-style",[122,316,136],{"class":135},[122,318,319],{"class":155}," normal",[122,321,159],{"class":135},[122,323,325],{"class":124,"line":324},9,[122,326,165],{"class":135},[122,328,330],{"class":124,"line":329},10,[122,331,332],{"class":128},"\u002F* ... plus more font-face declarations for other unicode ranges\u002Fweights *\u002F\n",[61,334,335,338,339,342],{},[64,336,337],{},"Proxies and caches font requests."," Rather than using the original source URLs (to remote servers), we generate rewrites under the ",[53,340,341],{},"\u002F_fonts"," subpath. When accessed by your browser, we download the font from the remote server and cache it locally.",[61,344,345,348,349,351,352,357,358],{},[64,346,347],{},"Creates font fallback metrics."," If we have access to the font metrics (ascent, descent, line gap, character width, etc.) then we can generate a fallback ",[53,350,106],{}," declaration as well. The idea is that we 'morph' a local system font (like Arial or Times New Roman) to be as close as possible to the size of the web font, to decrease layout shift (",[92,353,356],{"href":354,"rel":355},"https:\u002F\u002Fweb.dev\u002Farticles\u002Fcls",[96],"read more about CLS",").",[113,359,361],{"className":115,"code":360,"language":117,"meta":118,"style":118},":root {\n  \u002F* This will generate fallbacks for local versions of Helvetica and Arial, adjusted to match Roboto's metrics. *\u002F\n  font-family: Roboto, Helvetica, Arial;\n  \u002F* If you provide a generic family (like serif or sans-serif), we will use a system font from that family. *\u002F\n  font-family: Merriweather, serif;\n}\n",[53,362,363,371,376,397,402,418],{"__ignoreMap":118},[122,364,365,367,369],{"class":124,"line":125},[122,366,136],{"class":135},[122,368,140],{"class":139},[122,370,143],{"class":135},[122,372,373],{"class":124,"line":132},[122,374,375],{"class":128},"  \u002F* This will generate fallbacks for local versions of Helvetica and Arial, adjusted to match Roboto's metrics. *\u002F\n",[122,377,378,380,382,385,387,390,392,395],{"class":124,"line":146},[122,379,150],{"class":149},[122,381,136],{"class":135},[122,383,384],{"class":155}," Roboto",[122,386,284],{"class":135},[122,388,389],{"class":155}," Helvetica",[122,391,284],{"class":135},[122,393,394],{"class":155}," Arial",[122,396,159],{"class":135},[122,398,399],{"class":124,"line":162},[122,400,401],{"class":128},"  \u002F* If you provide a generic family (like serif or sans-serif), we will use a system font from that family. *\u002F\n",[122,403,404,406,408,411,413,416],{"class":124,"line":254},[122,405,150],{"class":149},[122,407,136],{"class":135},[122,409,410],{"class":155}," Merriweather",[122,412,284],{"class":135},[122,414,415],{"class":155}," serif",[122,417,159],{"class":135},[122,419,420],{"class":124,"line":267},[122,421,165],{"class":135},[61,423,424,427],{},[64,425,426],{},"Include fonts in build."," When you build your project, we'll copy across all the fonts used in your project so you don't need to make any external requests when loading your site. (Any that haven't already been cached in development are downloaded at build time.) Font file names are hashed and Nuxt will serve them with long-lived cache headers.",[44,429,431],{"id":430},"caching-fonts-between-builds","Caching fonts between builds",[49,433,434,435,438],{},"Font metadata and downloaded font files are cached on disk in ",[53,436,437],{},"node_modules\u002F.cache\u002Fnuxt\u002Ffonts\u002Fmeta",", relative to your project root. If you restore that directory in CI, no fonts are downloaded and no provider requests are made at all.",[113,440,445],{"className":441,"code":442,"filename":443,"language":444,"meta":118,"style":118},"language-yaml shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","- uses: actions\u002Fcache@v4\n  with:\n    path: node_modules\u002F.cache\u002Fnuxt\u002Ffonts\n    key: nuxt-fonts-${{ hashFiles('nuxt.config.ts') }}\n    restore-keys: nuxt-fonts-\n",".github\u002Fworkflows\u002Fbuild.yml","yaml",[53,446,447,460,468,478,488],{"__ignoreMap":118},[122,448,449,451,455,457],{"class":124,"line":125},[122,450,278],{"class":135},[122,452,454],{"class":453},"swJcz"," uses",[122,456,136],{"class":135},[122,458,459],{"class":194}," actions\u002Fcache@v4\n",[122,461,462,465],{"class":124,"line":132},[122,463,464],{"class":453},"  with",[122,466,467],{"class":135},":\n",[122,469,470,473,475],{"class":124,"line":146},[122,471,472],{"class":453},"    path",[122,474,136],{"class":135},[122,476,477],{"class":194}," node_modules\u002F.cache\u002Fnuxt\u002Ffonts\n",[122,479,480,483,485],{"class":124,"line":162},[122,481,482],{"class":453},"    key",[122,484,136],{"class":135},[122,486,487],{"class":194}," nuxt-fonts-${{ hashFiles('nuxt.config.ts') }}\n",[122,489,490,493,495],{"class":124,"line":254},[122,491,492],{"class":453},"    restore-keys",[122,494,136],{"class":135},[122,496,497],{"class":194}," nuxt-fonts-\n",[49,499,500],{},"A few things to check if the cache doesn't seem to take effect:",[502,503,504,515,536,547],"ul",{},[61,505,506,507,510,511,514],{},"The cache step must run ",[64,508,509],{},"after"," you install dependencies. Some package managers remove unknown directories inside ",[53,512,513],{},"node_modules",", which will delete a cache restored before install.",[61,516,517,520,521,524,525,528,529,532,533,535],{},[53,518,519],{},"actions\u002Fsetup-node"," with ",[53,522,523],{},"cache: 'pnpm'"," (or ",[53,526,527],{},"npm","\u002F",[53,530,531],{},"yarn",") caches the package manager store, not ",[53,534,513],{},", so it does not cover fonts.",[61,537,538,539,542,543,546],{},"With an exact ",[53,540,541],{},"key"," and no ",[53,544,545],{},"restore-keys",", a config change means a cache miss and a full re-download.",[61,548,549,550,553,554,557],{},"In Docker builds, ",[53,551,552],{},"node_modules\u002F.cache"," lives inside the build container. You need a cache mount (",[53,555,556],{},"RUN --mount=type=cache,target=\u002Fapp\u002Fnode_modules\u002F.cache",") or a persistent volume for it to survive.",[49,559,560,561,563,564,570],{},"If a path inside ",[53,562,513],{}," is awkward to cache, move it with the ",[92,565,567],{"href":566},"\u002Fget-started\u002Fconfiguration#cache",[53,568,569],{},"cache"," option.",[44,572,574],{"id":573},"module-hooks","Module Hooks",[49,576,577],{},"Nuxt Fonts exposes hooks for module authors to extend functionality.",[579,580,582],"h3",{"id":581},"fontsproviders",[53,583,584],{},"fonts:providers",[49,586,587],{},"Add or modify font providers after all modules have loaded.",[113,589,593],{"className":590,"code":591,"language":592,"meta":118,"style":118},"language-ts shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","nuxt.hook('fonts:providers', (providers) => {\n  providers['my-provider'] = defineFontProvider(\u002F* ... *\u002F)\n})\n","ts",[53,594,595,628,660],{"__ignoreMap":118},[122,596,597,600,602,605,607,609,611,613,615,618,621,623,626],{"class":124,"line":125},[122,598,599],{"class":155},"nuxt",[122,601,111],{"class":135},[122,603,604],{"class":210},"hook",[122,606,214],{"class":155},[122,608,198],{"class":135},[122,610,584],{"class":194},[122,612,198],{"class":135},[122,614,284],{"class":135},[122,616,617],{"class":135}," (",[122,619,620],{"class":247},"providers",[122,622,239],{"class":135},[122,624,625],{"class":139}," =>",[122,627,143],{"class":135},[122,629,630,633,636,638,641,643,646,649,652,654,657],{"class":124,"line":132},[122,631,632],{"class":155},"  providers",[122,634,635],{"class":453},"[",[122,637,198],{"class":135},[122,639,640],{"class":194},"my-provider",[122,642,198],{"class":135},[122,644,645],{"class":453},"] ",[122,647,648],{"class":135},"=",[122,650,651],{"class":210}," defineFontProvider",[122,653,214],{"class":453},[122,655,656],{"class":128},"\u002F* ... *\u002F",[122,658,659],{"class":453},")\n",[122,661,662,665],{"class":124,"line":146},[122,663,664],{"class":135},"}",[122,666,659],{"class":155},[579,668,670],{"id":669},"fontspublic-asset-context",[53,671,672],{},"fonts:public-asset-context",[49,674,675],{},"Access the font resolution context, useful for modules that need font URLs during prerender (e.g., OG image generation).",[113,677,679],{"className":590,"code":678,"language":592,"meta":118,"style":118},"nuxt.hook('fonts:public-asset-context', (context) => {\n\u002F\u002F context.renderedFontURLs: Map\u003Cfilename, sourceUrl>\n\u002F\u002F Populated during vite build\n})\n",[53,680,681,710,715,720],{"__ignoreMap":118},[122,682,683,685,687,689,691,693,695,697,699,701,704,706,708],{"class":124,"line":125},[122,684,599],{"class":155},[122,686,111],{"class":135},[122,688,604],{"class":210},[122,690,214],{"class":155},[122,692,198],{"class":135},[122,694,672],{"class":194},[122,696,198],{"class":135},[122,698,284],{"class":135},[122,700,617],{"class":135},[122,702,703],{"class":247},"context",[122,705,239],{"class":135},[122,707,625],{"class":139},[122,709,143],{"class":135},[122,711,712],{"class":124,"line":132},[122,713,714],{"class":128},"\u002F\u002F context.renderedFontURLs: Map\u003Cfilename, sourceUrl>\n",[122,716,717],{"class":124,"line":146},[122,718,719],{"class":128},"\u002F\u002F Populated during vite build\n",[122,721,722,724],{"class":124,"line":162},[122,723,664],{"class":135},[122,725,659],{"class":155},[727,728,729],"style",{},"html pre.shiki code .sHwdD, html code.shiki .sHwdD{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .sqsOY, html code.shiki .sqsOY{--shiki-light:#8796B0;--shiki-default:#B2CCD6;--shiki-dark:#B2CCD6}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .s7zQu, html code.shiki .s7zQu{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .s2Zo4, html code.shiki .s2Zo4{--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF}html pre.shiki code .sHdIc, html code.shiki .sHdIc{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#EEFFFF;--shiki-default-font-style:italic;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sbssI, html code.shiki .sbssI{--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C}html pre.shiki code .swJcz, html code.shiki .swJcz{--shiki-light:#E53935;--shiki-default:#F07178;--shiki-dark:#F07178}",{"title":118,"searchDepth":132,"depth":132,"links":731},[732,733,734],{"id":46,"depth":132,"text":47},{"id":430,"depth":132,"text":431},{"id":573,"depth":132,"text":574,"children":735},[736,737],{"id":581,"depth":146,"text":584},{"id":669,"depth":146,"text":672},"Find out how Nuxt Fonts works behind the scenes to optimize fonts in your project.","md",null,{},true,{"title":31,"description":738},"YA0RTr45yPwfWXZ3HhX6ToleGTEuONwT926yid_OSJY",[746,748],{"title":26,"path":27,"stem":28,"description":747,"children":-1},"Breaking changes and migration steps when upgrading to the latest version of @nuxt\u002Ffonts.",{"title":35,"path":36,"stem":37,"description":749,"children":-1},"We can never thank you enough for your contributions.",1788752882865]