1"use strict";(self.webpackChunk_stencil_stencil_site=self.webpackChunk_stencil_stencil_site||[]).push([[11988],{61536:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>s,default:()=>l,frontMatter:()=>o,metadata:()=>d,toc:()=>a});var i=t(74848),r=t(28453);const o={title:"Debugging With VS Code",sidebar_label:"VS Code Debugging",description:"How to debug a Stencil component using VS Code",slug:"/vs-code-debugging"},s="Debugging With VS Code",d={id:"guides/vs-code-debugging",title:"Debugging With VS Code",description:"How to debug a Stencil component using VS Code",source:"@site/versioned_docs/version-v4.35/guides/vs-code-debugging.md",sourceDirName:"guides",slug:"/vs-code-debugging",permalink:"/docs/v4.35/vs-code-debugging",draft:!1,unlisted:!1,editUrl:"https://github.com/ionic-team/stencil-site/tree/main/versioned_docs/version-v4.35/guides/vs-code-debugging.md",tags:[],version:"v4.35",frontMatter:{title:"Debugging With VS Code",sidebar_label:"VS Code Debugging",description:"How to debug a Stencil component using VS Code",slug:"/vs-code-debugging"},sidebar:"docs",previous:{title:"Typed Components",permalink:"/docs/v4.35/typed-components"},next:{title:"Web Workers",permalink:"/docs/v4.35/web-workers"}},c={},a=[{value:"Requirements for Debugging",id:"requirements-for-debugging",level:2},{value:"Debugging Stencil Components In a Web App",id:"debugging-stencil-components-in-a-web-app",level:2},{value:"Configuring the VS Code Debugger",id:"configuring-the-vs-code-debugger",level:3},{value:"Debugging Static Site Generation (SSG)",id:"debugging-static-site-generation-ssg",level:2},{value:"Overview",id:"overview",level:3},{value:"Tips for Debugging Prerendering",id:"tips-for-debugging-prerendering",level:3},{value:"Configuring the VS Code Debugger",id:"configuring-the-vs-code-debugger-1",level:3}];function g(e){const n={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",pre:"pre",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"debugging-with-vs-code",children:"Debugging With VS Code"})}),"\n",(0,i.jsxs)(n.p,{children:["VS Code offers a streamlined debugging experience that can be started with a single click when using ",(0,i.jsx)(n.a,{href:"https://code.visualstudio.com/docs/editor/debugging#_launch-configurations",children:"launch configurations"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["If you're unfamiliar with using the VS Code debugger in general, please visit the ",(0,i.jsx)(n.a,{href:"https://code.visualstudio.com/docs/editor/debugging",children:"VS Code debugger documentation"})," for a primer."]}),"\n",(0,i.jsx)(n.h2,{id:"requirements-for-debugging",children:"Requirements for Debugging"}),"\n",(0,i.jsxs)(n.p,{children:["In order for a debugger to function, the Stencil project must be configured to generate source maps for the compiled web components back to the source code. As of Stencil v3, source maps are generated by default, but be sure to double-check the project's Stencil config does not disable this behavior. More information regarding source maps in Stencil can be found in the ",(0,i.jsx)(n.a,{href:"/docs/v4.35/config#sourcemap",children:"project configuration documentation"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"debugging-stencil-components-in-a-web-app",children:"Debugging Stencil Components In a Web App"}),"\n",(0,i.jsx)(n.p,{children:"It's a common use case to want to step through a web component's code as it executes in the browser and VS Code makes that process simple. Combining the debugger with Stencil's dev server in watch mode will allow you to debug changes as they're made."}),"\n",(0,i.jsx)(n.h3,{id:"configuring-the-vs-code-debugger",children:"Configuring the VS Code Debugger"}),"\n",(0,i.jsxs)(n.p,{children:["To debug Stencil components as they run in a browser (web app), create (or edit) the ",(0,i.jsx)(n.code,{children:".vscode/launch.json"})," file with the following configuration:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",metastring:'title=".vscode/launch.json"',children:'{\n ...,\n "configurations": [\n ...,\n {\n "type": "chrome",\n "request": "launch",\n "name": "Launch Chrome against localhost",\n "url": "http://localhost:3333",\n "sourceMaps": true,\n "sourceMapPathOverrides": {\n "*": "${webRoot}/*"\n }\n }\n ]\n}\n'})}),"\n",(0,i.jsxs)(n.admonition,{type:"note",children:[(0,i.jsxs)(n.p,{children:["If your Stencil project is
1within a monorepo structure, you may want (or need) to add the ",(0,i.jsx)(n.code,{children:"webRoot"})," option to the above config to point to the Stencil project's directory. For instance, if you have your Stencil project at ",(0,i.jsx)(n.code,{children:"/packages/stencil-library"}),", you would add the following to the config:"]}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",children:'{\n ...,\n "webRoot": "${workspaceFolder}/packages/stencil-library",\n}\n'})})]}),"\n",(0,i.jsxs)(n.p,{children:["This will create a configuration to open a Chrome debugger instance on port 3333 (the default port used by the Stencil dev server). To use this configuration, start a Stencil dev server (running ",(0,i.jsx)(n.code,{children:"npm start"})," in a ",(0,i.jsx)(n.a,{href:"https://stenciljs.com/docs/getting-started",children:"Stencil component starter project"}),") and then run the configuration from the VS Code debugger tab. At this point, any breakpoints set in the component source code will pause browser execution when hit."]}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:["If your Stencil project is ",(0,i.jsx)(n.a,{href:"https://stenciljs.com/docs/dev-server#dev-server-config",children:"configured to use a different port"})," for the dev server, you will need to update the ",(0,i.jsx)(n.code,{children:"url"})," property in the debugger configuration with the correct port."]})}),"\n",(0,i.jsx)(n.h2,{id:"debugging-static-site-generation-ssg",children:"Debugging Static Site Generation (SSG)"}),"\n",(0,i.jsx)(n.p,{children:"Static Site Generation, also known as prerendering, executes your components at build time to generate a snapshot of the rendered styles and markup to be efficiently served to search engines and users on first request."}),"\n",(0,i.jsx)(n.p,{children:"Since this step runs in a Node.js process instead of a browser, debugging can't be done directly in the browser. However, debugging is straightforward using existing Node.js debugging techniques."}),"\n",(0,i.jsx)(n.h3,{id:"overview",children:"Overview"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"stencil build --prerender"})," command will first build the hydrate script for a NodeJS environment, then prerender the site using the build. For a production build this is probably ideal."]}),"\n",(0,i.jsxs)(n.p,{children:["However, while debugging you may not need to keep rebuilding the hydrate script, but you only need to debug through the prerendering process. Stencil creates a file in ",(0,i.jsx)(n.code,{children:"dist/hydrate"})," that is used to actually execute your components."]}),"\n",(0,i.jsxs)(n.p,{children:["To only prerender (and avoid rebuilding), you can use the ",(0,i.jsx)(n.code,{children:"stencil prerender dist/hydrate/index.js"})," command, with the path to the script as a flag."]}),"\n",(0,i.jsx)(n.h3,{id:"tips-for-debugging-prerendering",children:"Tips for Debugging Prerendering"}),"\n",(0,i.jsxs)(n.p,{children:["By default, prerendering will start by rendering the homepage, find links within the homepage, and continue to crawl the entire site as it finds more links. While debugging, it might be easier to ",(0,i.jsx)(n.em,{children:"not"})," crawl every URL in the site, but rather have it only prerender one page. To disable crawling, set the prerender config ",(0,i.jsx)(n.code,{children:"crawlUrls: false"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["Next, you can use the ",(0,i.jsx)(n.code,{children:"entryUrls"})," config to provide an array of paths to prerender, rather than starting at the homepage."]}),"\n",(0,i.jsxs)(n.p,{children:["Additionally, console logs that are printed within the runtime are suppressed while prerendering (otherwise the terminal would be overloaded with logs). By setting ",(0,i.jsx)(n.code,{children:"runtimeLogging: true"}),", the runtime console logs will be printed in the terminal. Below is an example setup for prerender debugging:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-tsx",metastring:'title="prerender.config.ts"',children:"import { PrerenderConfig } from '@stencil/core';
1\n\nexport const config: PrerenderConfig = {\n crawlUrls: false,\n entryUrls: ['/example'],\n hydrateOptions: (_url) => {\n return {\n runtimeLogging: true,\n };\n },\n};\n"})}),"\n",(0,i.jsx)(n.h3,{id:"configuring-the-vs-code-debugger-1",children:"Configuring the VS Code Debugger"}),"\n",(0,i.jsxs)(n.p,{children:["To debug the Stencil prerender process, create (or edit) the ",(0,i.jsx)(n.code,{children:"launch.json"})," file with the following configuration:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",metastring:'title="launch.json"',children:'{\n ...,\n "configurations": [\n ...,\n {\n "type": "node",\n "request": "launch",\n "name": "Prerender",\n "args": [\n "${workspaceFolder}/node_modules/@stencil/core/bin/stencil",\n "prerender",\n "${workspaceFolder}/dist/hydrate/index.js",\n "--max-workers=0",\n "--config=${workspaceFolder}/stencil.config.ts"\n ],\n "protocol": "inspector"\n }\n ]\n}\n'})}),"\n",(0,i.jsxs)(n.p,{children:["This creates a new debugging configuration using the script that hydrates the app. We're starting up the ",(0,i.jsx)(n.code,{children:"stencil prerender"})," command, and providing it a path to where\nthe hydrate script can be found. Next we're using ",(0,i.jsx)(n.code,{children:"--max-workers=0"})," so we do not fork numerous processes to each of your CPUs which will make it difficult to debug."]})]})}function l(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(g,{...e})}):g(e)}},28453:(e,n,t)=>{t.d(n,{R:()=>s,x:()=>d});var i=t(96540);const r={},o=i.createContext(r);function s(e){const n=i.useContext(o);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:s(e.components),i.createElement(o.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.