[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-navigation":3,"docs-page-automatic-updates":157},[4,43,57,65,114,138],{"id":5,"group":6,"pages":7},"get-started","Get started",[8,13,18,23,28,33,38],{"path":9,"title":10,"description":11,"navTitle":10,"group":6,"order":12},"\u002Fdocs\u002Fgetting-started","Getting started","Create your app from the kit, run it locally with no credentials, make yourself superadmin and find where your own code goes.",1,{"path":14,"title":15,"description":16,"navTitle":15,"group":6,"order":17},"\u002Fdocs\u002Flayout","Project structure","Where code lives by where it runs, and which server\u002F directories turn a new file into a route, a job or a provider.",2,{"path":19,"title":20,"description":21,"navTitle":20,"group":6,"order":22},"\u002Fdocs\u002Fconfiguration","Configuration","starter.config.ts switches each part of the kit and its providers, environment variables hold the secrets: every key and what it changes.",3,{"path":24,"title":25,"description":26,"navTitle":25,"group":6,"order":27},"\u002Fdocs\u002Ftemplate","Updating from the kit","Keep the kit as a git remote and take each update as one commit you review, with pnpm kit:update, then resolve what conflicts.",4,{"path":29,"title":30,"description":31,"navTitle":30,"group":6,"order":32},"\u002Fdocs\u002Fautomatic-updates","Automatic updates","A daily GitHub Actions run opens a pull request for each kit update: the token and variable to set, how to read what it opens, and what to do when it fails.",5,{"path":34,"title":35,"description":36,"navTitle":35,"group":6,"order":37},"\u002Fdocs\u002Fdeployment","Deployment","Ship the app as one Cloudflare Worker: create the resources, set the secrets, deploy main from GitHub Actions or your machine.",6,{"path":39,"title":40,"description":41,"navTitle":40,"group":6,"order":42},"\u002Fdocs\u002Fmcp","MCP server","Connect Claude Code, Cursor or VS Code to https:\u002F\u002Fnuxter.app\u002Fmcp, so your agent searches and reads these docs and their design notes.",7,{"id":44,"group":45,"pages":46},"accounts","Accounts",[47,52],{"path":48,"title":49,"description":50,"navTitle":49,"group":45,"order":51},"\u002Fdocs\u002Ftenancy","Organizations","Scope routes and pages to an organization, and work with its members, roles, seats, invitations and a second level such as branches.",9,{"path":53,"title":54,"description":55,"navTitle":54,"group":45,"order":56},"\u002Fdocs\u002Fpermissions","Roles and permissions","Routes check permissions that an account’s role or its organization’s plan grants: checking one, adding a role, and the staff tools.",10,{"id":58,"group":59,"pages":60},"payments","Payments",[61],{"path":62,"title":59,"description":63,"navTitle":59,"group":59,"order":64},"\u002Fdocs\u002Fpayments","Sell plans through Stripe, Polar or Creem: define plans, connect a provider, gate features, trials, coupons and refunds.",11,{"id":66,"group":67,"pages":68},"building-blocks","Building blocks",[69,74,79,84,89,94,99,104,109],{"path":70,"title":71,"description":72,"navTitle":71,"group":67,"order":73},"\u002Fdocs\u002Fdatabase","Database","Postgres through Drizzle, on Hyperdrive in production and PGlite locally: add a table, query, transactions, migrations and seed data.",12,{"path":75,"title":76,"description":77,"navTitle":76,"group":67,"order":78},"\u002Fdocs\u002Fbackground-jobs","Background jobs","Run work after the response on Cloudflare Queues with retries: add and enqueue a job, run jobs locally, and schedule cron tasks.",13,{"path":80,"title":81,"description":82,"navTitle":81,"group":67,"order":83},"\u002Fdocs\u002Fevents","Events","React to what the kit does by adding a file to server\u002Flisteners\u002F, fire events of your own, and look up every event’s payload.",14,{"path":85,"title":86,"description":87,"navTitle":86,"group":67,"order":88},"\u002Fdocs\u002Femail","Email","Set up sending, send your own mail with deliverEmail, change the templates and wording, handle unsubscribes and add a provider.",15,{"path":90,"title":91,"description":92,"navTitle":91,"group":67,"order":93},"\u002Fdocs\u002Fcontact","Contact","A \u002Fcontact page that mails you a message or shows your address after a Turnstile check: choose the channels, set the address, know the limits.",16,{"path":95,"title":96,"description":97,"navTitle":96,"group":67,"order":98},"\u002Fdocs\u002Fnotifications","Notifications","The dashboard bell: add a notification type, send one with notify(), and how categories, opt-outs and retention apply.",17,{"path":100,"title":101,"description":102,"navTitle":101,"group":67,"order":103},"\u002Fdocs\u002Fstorage","Storage","Uploads in R2 with one policy per purpose: add a purpose, accept an upload, replace or delete a file, and serve it to its owner.",18,{"path":105,"title":106,"description":107,"navTitle":106,"group":67,"order":108},"\u002Fdocs\u002Ffeature-flags","Feature flags","Declare typed flags in starter.config.ts, read them with flag() or useFlag(), roll them out by rule or percentage, and add a provider.",19,{"path":110,"title":111,"description":112,"navTitle":111,"group":67,"order":113},"\u002Fdocs\u002Fai","AI","Call models from server code by role: text, images, speech, transcription, embeddings and video, with provider fallbacks.",20,{"id":115,"group":116,"pages":117},"web","Web",[118,123,128,133],{"path":119,"title":120,"description":121,"navTitle":120,"group":116,"order":122},"\u002Fdocs\u002Fsecurity-headers","Security headers","The Content-Security-Policy and hardening headers on every response: allow another origin, keep tokens out of Referer, accept cross-site posts.",21,{"path":124,"title":125,"description":126,"navTitle":125,"group":116,"order":127},"\u002Fdocs\u002Frate-limiting","Rate limiting","Cap how often a caller hits a route with requireRateLimit, count only failures, space out sends, and protect the zone.",22,{"path":129,"title":130,"description":131,"navTitle":130,"group":116,"order":132},"\u002Fdocs\u002Fanalytics","Analytics","Product analytics and ad conversions sent from the server with no browser script: add an event, connect a provider, and handle consent.",23,{"path":134,"title":135,"description":136,"navTitle":135,"group":116,"order":137},"\u002Fdocs\u002Fobservability","Observability","Find a failed request by its id, send faults to Sentry or Better Stack, report an error you caught, and change the error page.",24,{"id":139,"group":140,"pages":141},"content-and-look","Content and look",[142,147,152],{"path":143,"title":144,"description":145,"navTitle":144,"group":140,"order":146},"\u002Fdocs\u002Fblog","Blog","Markdown posts with an RSS feed per language, and workflows that draft posts with an AI model and open each one as a pull request.",25,{"path":148,"title":149,"description":150,"navTitle":149,"group":140,"order":151},"\u002Fdocs\u002Flanguages","Languages","Add or remove a language, write copy in the locale files, and write code, refusals and links that follow the reader’s language.",26,{"path":153,"title":154,"description":155,"navTitle":154,"group":140,"order":156},"\u002Fdocs\u002Ftheme","Theme","Change the brand colour and font, and build dashboard sections, list pages, loading placeholders and charts that match the kit.",27,{"page":158,"surround":1543,"linksToKit":1546},{"path":29,"title":30,"description":31,"navTitle":30,"group":6,"seo":159,"body":161},{"title":160,"description":31},"Starter kit updates as GitHub pull requests",{"type":162,"value":163,"toc":1521},"minimark",[164,168,185,188,193,233,237,240,245,248,260,307,315,319,347,351,365,421,435,439,471,479,483,490,496,500,511,547,573,577,586,644,648,715,725,729,735,798,801,882,892,896,906,947,950,985,992,1003,1006,1009,1026,1032,1036,1039,1099,1114,1117,1157,1171,1184,1188,1191,1222,1225,1228,1414,1420,1423,1426,1445,1453,1457,1517],[165,166,30],"h1",{"id":167},"automatic-updates",[169,170,171,172,176,177,180,181,184],"p",{},"Your app ships with a GitHub Actions workflow, ",[173,174,175],"code",{},"kit-update",", that takes kit\nupdates for you. Once a day it checks the kit, and when the kit has something\nnew it does what ",[173,178,179],{},"pnpm kit:update"," does (",[182,183,25],"a",{"href":24},")\non a branch of its own and opens a pull request. You read the pull request and\nmerge it. You need this page once, to turn the workflow on, and again whenever\na pull request asks something of you.",[169,186,187],{},"It serves an app that is the whole repository. An app in a folder of a\nmonorepo keeps taking updates by hand.",[189,190,192],"h2",{"id":191},"how-it-works","How it works",[194,195,196,203,210,224,230],"ol",{},[197,198,199,200,202],"li",{},"Every day at 05:17 UTC, GitHub runs ",[173,201,175],{}," in your app's repository.\nUntil you turn it on, that run is skipped and does nothing.",[197,204,205,206,209],{},"It reads ",[173,207,208],{},".template-base"," on your default branch to see which kit commit\nyour app is at, and asks the kit what changed since. When nothing did, it\nstops, in about a minute.",[197,211,212,213,215,216,219,220,223],{},"When something did, it builds the update on a branch named ",[173,214,175],{},", as\none commit titled ",[173,217,218],{},"chore(template): update to main"," (or ",[173,221,222],{},"update to v1.4.0","\non releases), and opens a pull request from it into your default branch.",[197,225,226,227,229],{},"The pull request runs your CI like any other. Its description, and a status\nnamed ",[173,228,175],{},", say whether it is safe to merge. GitHub notifies you of\neach new one.",[197,231,232],{},"You merge it. Merging deploys it, like any other merge to your default\nbranch. The next run proposes whatever the kit changed after it.",[189,234,236],{"id":235},"turn-it-on","Turn it on",[169,238,239],{},"You need a token, so the workflow can act as you, and a variable that says\nwhich updates to take. Both go in your app repository's settings. The four\nsteps below take about ten minutes, in this order.",[241,242,244],"h3",{"id":243},"create-a-token","Create a token",[169,246,247],{},"A personal access token is a password that GitHub issues for scripts, limited\nto what you allow. The workflow needs one because GitHub's built-in token\ncannot do this job: a pull request it opens waits for a click before any of\nyour CI runs, and it can never push a kit change to a workflow file.",[169,249,250,251,255,256,259],{},"The simplest setup is one ",[252,253,254],"strong",{},"classic"," token. If you were invited to the kit\nrepository, ",[173,257,258],{},"nuxter-app\u002Fkit",", on your own, GitHub treats you as an outside\ncollaborator there, and a classic token is the only kind it lets you use to\nread it.",[194,261,262,269,279,286,300],{},[197,263,264,265,268],{},"On GitHub, open your profile picture, then ",[252,266,267],{},"Settings → Developer settings →\nPersonal access tokens → Tokens (classic) → Generate new token (classic)",".",[197,270,271,272,275,276,268],{},"In ",[252,273,274],{},"Note",", write what it is for, such as ",[173,277,278],{},"kit-update for my-app",[197,280,281,282,285],{},"Pick an ",[252,283,284],{},"Expiration",". From 30 days before that date, each run warns you,\nand so does a pull request it opens or rebuilds.",[197,287,288,289,292,293,296,297,268],{},"Under ",[252,290,291],{},"Select scopes",", tick ",[173,294,295],{},"repo"," and ",[173,298,299],{},"workflow",[197,301,302,303,306],{},"Press ",[252,304,305],{},"Generate token"," and copy it. GitHub shows it once.",[169,308,309,310,314],{},"A classic token reaches every repository your account can. To keep the token\nthat pushes to your app narrower, use ",[182,311,313],{"href":312},"#two-tokens-instead-of-one","two tokens","\ninstead.",[241,316,318],{"id":317},"add-it-to-your-app","Add it to your app",[194,320,321,327,337],{},[197,322,323,324,268],{},"Open your app's repository on GitHub, then ",[252,325,326],{},"Settings → Secrets and\nvariables → Actions",[197,328,329,330,333,334,268],{},"On the ",[252,331,332],{},"Secrets"," tab, press ",[252,335,336],{},"New repository secret",[197,338,339,340,343,344,268],{},"Name it ",[173,341,342],{},"KIT_UPDATE_TOKEN",", paste the token as its value, and press ",[252,345,346],{},"Add\nsecret",[241,348,350],{"id":349},"choose-what-to-take","Choose what to take",[169,352,353,354,333,357,360,361,364],{},"On the same page, open the ",[252,355,356],{},"Variables",[252,358,359],{},"New repository\nvariable",", name it ",[173,362,363],{},"KIT_UPDATE_CHANNEL",", and give it one of these values:",[366,367,368,381],"table",{},[369,370,371],"thead",{},[372,373,374,378],"tr",{},[375,376,377],"th",{},"Value",[375,379,380],{},"What the daily run does",[382,383,384,398,411],"tbody",{},[372,385,386,392],{},[387,388,389],"td",{},[173,390,391],{},"main",[387,393,394,395,397],{},"Takes every change on the kit's ",[173,396,391],{},", which is always deployable.",[372,399,400,405],{},[387,401,402],{},[173,403,404],{},"release",[387,406,407,408,268],{},"Takes published releases only, such as ",[173,409,410],{},"v1.4.0",[372,412,413,418],{},[387,414,415],{},[173,416,417],{},"off",[387,419,420],{},"Nothing: the daily run is skipped, as it is while the variable is not set.",[169,422,423,424,426,427,429,430,434],{},"You can switch at any time. Moving from ",[173,425,391],{}," to ",[173,428,404],{}," waits for a release\nnewer than the kit commit your app is at.\n",[182,431,433],{"href":432},"\u002Fdocs\u002Ftemplate#releases","Releases"," says what a release number tells you.",[241,436,438],{"id":437},"check-that-it-works","Check that it works",[194,440,441,451,460],{},[197,442,443,444,447,448,450],{},"Open the repository's ",[252,445,446],{},"Actions"," tab and pick ",[252,449,175],{}," in the list on\nthe left.",[197,452,302,453,456,457,459],{},[252,454,455],{},"Run workflow"," on the right, leave the fields as they are, and press\nthe green ",[252,458,455],{}," button.",[197,461,462,463,466,467,470],{},"Open the run when it finishes. Its summary says what it did, such as\n",[173,464,465],{},"The app already has the kit's main (…)."," or\n",[173,468,469],{},"#12 proposes the kit's main (…)",", with a link to the pull request.",[169,472,473,474,478],{},"A red run says what to fix, as ",[182,475,477],{"href":476},"#when-a-run-fails","When a run fails"," lists.",[241,480,482],{"id":481},"on-github-free","On GitHub Free",[169,484,485,486,489],{},"On a personal account, or an organization on GitHub Free, set the secret and\nthe variable in every app repository: a private repository there sees only its\nown. An organization on GitHub Team or Enterprise can set them once, under the\norganization's own ",[252,487,488],{},"Settings → Secrets and variables → Actions",", for the\nrepositories it picks.",[169,491,492,493,495],{},"A private repository on GitHub Free or Pro cannot have draft pull requests.\nWhere the workflow would make the pull request a draft, because the update\nneeds you first, it leaves it open for review instead, whether it opens the\npull request or rebuilds one, and its Warnings section says so. The highlighted\nline and the red ",[173,494,175],{}," status are the warning too.",[241,497,499],{"id":498},"two-tokens-instead-of-one","Two tokens instead of one",[169,501,502,503,506,507,510],{},"A ",[252,504,505],{},"fine-grained"," token can be limited to the app repositories you pick. Create\nit under ",[252,508,509],{},"Personal access tokens → Fine-grained tokens",", with:",[512,513,514,520,526],"ul",{},[197,515,516,519],{},[252,517,518],{},"Resource owner",": the account or organization that owns your app.",[197,521,522,525],{},[252,523,524],{},"Repository access",": only the app repositories.",[197,527,528,531,532,535,536,539,540,543,544,268],{},[252,529,530],{},"Repository permissions",": ",[252,533,534],{},"Contents",", ",[252,537,538],{},"Pull requests"," and\n",[252,541,542],{},"Workflows",", each set to ",[252,545,546],{},"Read and write",[169,548,549,550,553,554,556,557,560,561,563,564,566,567,569,570,572],{},"Organizations cap these tokens at 366 days by default, and one that targets an\norganization may wait for an owner to approve it. A fine-grained token reaches\none owner's repositories only, so it cannot also read the kit. Add a second\nsecret, ",[173,551,552],{},"KIT_READ_TOKEN",", that can: a classic token with the ",[173,555,295],{}," scope if\nyou were invited to the kit alone, or, if you are a member of the ",[173,558,559],{},"nuxter-app","\norganization, a fine-grained token with ",[173,562,559],{}," as its resource owner and\n",[252,565,534],{}," read on the kit. The workflow reads the kit with\n",[173,568,552],{}," when it is set, and with ",[173,571,342],{}," otherwise. Runs\nwarn of either token's expiry, from 30 days before.",[189,574,576],{"id":575},"run-it-now","Run it now",[169,578,579,582,583,585],{},[252,580,581],{},"Actions → kit-update → Run workflow"," runs it without waiting for the next\nday. It needs ",[173,584,342],{}," but not the variable. The form has three\nfields:",[366,587,588,598],{},[369,589,590],{},[372,591,592,595],{},[375,593,594],{},"Field",[375,596,597],{},"What it does",[382,599,600,625,633],{},[372,601,602,605],{},[387,603,604],{},"Which kit to take",[387,606,607,610,611,613,614,616,617,619,620,622,623,268],{},[173,608,609],{},"configured"," follows ",[173,612,363],{},", and ",[173,615,391],{}," when it is not set. ",[173,618,391],{}," or ",[173,621,404],{}," checks that channel once, even while the variable is ",[173,624,417],{},[372,626,627,630],{},[387,628,629],{},"Rebuild the open pull request",[387,631,632],{},"A tick builds the open pull request again even when it still merges cleanly, unless its branch carries a commit of yours, and takes an update whose pull request you closed.",[372,634,635,638],{},[387,636,637],{},"The kit commit this app last took",[387,639,640,641,643],{},"Leave it empty unless a run asks for it (",[182,642,477],{"href":476},"). It takes a kit commit or tag.",[189,645,647],{"id":646},"what-each-run-does","What each run does",[512,649,650,656,665,690,700,706],{},[197,651,652,655],{},[252,653,654],{},"The kit has nothing new"," for your channel: it stops in about a minute.",[197,657,658,661,662,664],{},[252,659,660],{},"No kit update is open",": it builds one on the ",[173,663,175],{}," branch and opens\na pull request, as a draft when something needs you first.",[197,666,667,670,671,535,674,619,677,680,681,684,685,689],{},[252,668,669],{},"A kit update is open",": it leaves it alone, even when the kit has moved on.\nMerge it, and the next run proposes the rest. It builds the branch again only\nwhen the pull request no longer merges into your default branch, when your\n",[173,672,673],{},"package.json",[173,675,676],{},"pnpm-lock.yaml",[173,678,679],{},"pnpm-workspace.yaml"," changed on the\ndefault branch, when your default branch was merged into it with nothing else\nchanged, as GitHub's ",[252,682,683],{},"Update branch"," button does, or when you run it with\n",[686,687,688],"em",{},"Rebuild"," ticked.",[197,691,692,695,696,268],{},[252,693,694],{},"You closed the pull request without merging",": see\n",[182,697,699],{"href":698},"#close-the-pull-request","Close the pull request",[197,701,702,705],{},[252,703,704],{},"You pushed a commit of your own to the branch",", to settle a conflict for\nexample: it leaves the branch alone while the pull request is open, and\ncomments once on it when the kit has moved past it. Merge or close the pull\nrequest, and it carries on. A plain merge of your default branch does not\ncount: the next run builds the branch again over it.",[197,707,708,711,712,714],{},[252,709,710],{},"You took the update by hand"," with ",[173,713,179],{},": if your default\nbranch now has the kit's latest commit for your channel, the next run closes\nthe pull request, or comments once that it is yours to close when the branch\ncarries a commit of yours. If the kit has moved on since, the pull request\ncounts as an open kit update, as above, and is rebuilt to propose the rest\nonly for the reasons listed there.",[169,716,717,718,619,721,724],{},"Merge with ",[252,719,720],{},"Squash and merge",[252,722,723],{},"Create a merge commit",", whichever your\nrepository allows.",[189,726,728],{"id":727},"read-the-pull-request","Read the pull request",[169,730,731,732,734],{},"The description opens with the two kit commits the update moves between, a\nlink that compares them on the kit, and a highlighted line that says whether to\nmerge. The ",[173,733,175],{}," status among the pull request's checks repeats it:",[366,736,737,750],{},[369,738,739],{},[372,740,741,744,747],{},[375,742,743],{},"Highlighted line",[375,745,746],{},"Status",[375,748,749],{},"What to do",[382,751,752,765,785],{},[372,753,754,759,762],{},[387,755,756],{},[252,757,758],{},"No conflicts with your files.",[387,760,761],{},"Green",[387,763,764],{},"Wait for CI, then merge.",[372,766,767,772,775],{},[387,768,769],{},[252,770,771],{},"Read before merging",[387,773,774],{},"Yellow",[387,776,777,778,296,781,784],{},"Read ",[252,779,780],{},"Before you merge",[252,782,783],{},"Conflicts"," first. The update changes production, or Claude resolved conflicts.",[372,786,787,792,795],{},[387,788,789],{},[252,790,791],{},"Do not merge yet",[387,793,794],{},"Red",[387,796,797],{},"A file needs you, the lockfile was not rebuilt, or the kit's changelog lists a step to take first. The line says which, and the pull request is a draft where drafts exist.",[169,799,800],{},"Under it, each section appears only when it has something to say:",[512,802,803,823,841,850,864,870,876],{},[197,804,805,807,808,814,815,818,819,822],{},[252,806,780],{},": the steps the kit's ",[182,809,811],{"href":810},"\u002Fchangelog",[173,812,813],{},"CHANGELOG.md","\nadded under ",[686,816,817],{},"Before you update",", the new kit migrations that merging applies\nto your production database, every breaking kit commit, and a change to the\nkit's ",[173,820,821],{},"wrangler.jsonc",", after which you check that every binding and resource\nname in yours still points at your app's own resources. A new changelog step\nmakes the pull request a draft.",[197,824,825,827,828,830,831,833,834,535,836,466,838,840],{},[252,826,783],{},": a table of every file git could not merge on its own, what\neach side did, and how it ended. A file both sides changed in different\nplaces merges without a conflict and is not listed. ",[173,829,673],{}," is merged\nkey by key when you and the kit changed different keys. ",[173,832,676],{},"\nnever needs merging by hand: when it conflicts, the kit's is taken, and\nwhenever the kit changed ",[173,835,673],{},[173,837,676],{},[173,839,679],{},", pnpm rebuilds the lockfile with your packages added\nback. A text file nobody resolved keeps its conflict markers, a binary file\nboth sides changed keeps your version, a file you deleted stays deleted, and\na file the kit deleted or moved keeps your version. Each says so and makes\nthe pull request a draft.",[197,842,843,846,847,849],{},[252,844,845],{},"Lockfile",": why ",[173,848,676],{}," could not be rebuilt.",[197,851,852,855,856,858,859,863],{},[252,853,854],{},"Your files that replace kit files this update changed",": the same list\n",[173,857,179],{}," prints, with the command that shows each kit change\n(",[182,860,862],{"href":861},"\u002Fdocs\u002Ftemplate#your-replacements-the-update-changed","Your replacements the update changed",").\nThe update never touches these files. Carry over what your copy should have,\na security fix above all.",[197,865,866,869],{},[252,867,868],{},"Your dependencies the lockfile moved",": your own packages that rebuilding\nthe lockfile moved within their ranges.",[197,871,872,875],{},[252,873,874],{},"Warnings",": a token about to expire, a step the workflow could not finish,\nand the like.",[197,877,878,881],{},[252,879,880],{},"Kit commits",": the subject of every kit commit the update brings.",[169,883,884,885,888,889,891],{},"A comment from ",[173,886,887],{},"github-actions"," then mentions the owner of ",[173,890,342],{},",\nso the pull request reaches you as a notification even though your own token\nopened it.",[241,893,895],{"id":894},"settle-a-conflict-yourself","Settle a conflict yourself",[169,897,898,899,901,902,905],{},"When ",[252,900,783],{}," marks a file ",[252,903,904],{},"Not resolved",", fix it on the branch:",[907,908,913],"pre",{"className":909,"code":910,"language":911,"meta":912,"style":912},"language-bash shiki shiki-themes github-light github-light github-dark","git fetch origin\ngit switch -C kit-update origin\u002Fkit-update\n","bash","",[173,914,915,930],{"__ignoreMap":912},[916,917,919,923,927],"span",{"class":918,"line":12},"line",[916,920,922],{"class":921},"snPdu","git",[916,924,926],{"class":925},"sIIMD"," fetch",[916,928,929],{"class":925}," origin\n",[916,931,932,934,937,941,944],{"class":918,"line":17},[916,933,922],{"class":921},[916,935,936],{"class":925}," switch",[916,938,940],{"class":939},"sBjJW"," -C",[916,942,943],{"class":925}," kit-update",[916,945,946],{"class":925}," origin\u002Fkit-update\n",[169,948,949],{},"A text file both sides changed keeps its conflict markers: edit it and remove\nthem. A file kept deleted, a file the kit deleted or moved, and a binary file\nboth sides changed already hold your side: leave them as they are, or bring in\nthe kit's version by hand. Then commit and push any change:",[907,951,953],{"className":909,"code":952,"language":911,"meta":912,"style":912},"git add -A\ngit commit -m \"chore(template): settle the kit update's conflicts\"\ngit push\n",[173,954,955,965,978],{"__ignoreMap":912},[916,956,957,959,962],{"class":918,"line":12},[916,958,922],{"class":921},[916,960,961],{"class":925}," add",[916,963,964],{"class":939}," -A\n",[916,966,967,969,972,975],{"class":918,"line":17},[916,968,922],{"class":921},[916,970,971],{"class":925}," commit",[916,973,974],{"class":939}," -m",[916,976,977],{"class":925}," \"chore(template): settle the kit update's conflicts\"\n",[916,979,980,982],{"class":918,"line":22},[916,981,922],{"class":921},[916,983,984],{"class":925}," push\n",[169,986,987,988,991],{},"Mark the pull request ",[252,989,990],{},"Ready for review"," if it is a draft, wait for CI, and\nmerge. From your first commit on, the workflow leaves the branch alone until\nthe pull request is merged or closed.",[169,993,994,995,997,998,1002],{},"You can also close the pull request and take the update with\n",[173,996,179],{}," on a branch of your own instead\n(",[182,999,1001],{"href":1000},"\u002Fdocs\u002Ftemplate#take-an-update","Take an update",").",[189,1004,699],{"id":1005},"close-the-pull-request",[169,1007,1008],{},"Closing a kit update without merging it skips that kit commit. The workflow\ndoes not open it again, and the next change to the kit opens a new pull\nrequest. That one starts from where your app is, so it brings the changes you\nskipped as well.",[512,1010,1011,1016,1023],{},[197,1012,1013,1014,689],{},"To take a skipped update after all, run the workflow with ",[686,1015,688],{},[197,1017,1018,1019,426,1021,268],{},"To stop for longer, set ",[173,1020,363],{},[173,1022,417],{},[197,1024,1025],{},"Commits you pushed to the branch stay reachable from the closed pull request.",[169,1027,1028,1029,1031],{},"Undoing one file's change on the branch and merging the rest declines that\nchange for good: merging still moves ",[173,1030,208],{}," to the new kit commit,\nso no later update brings it again.",[189,1033,1035],{"id":1034},"let-claude-resolve-conflicts","Let Claude resolve conflicts",[169,1037,1038],{},"The workflow can hand the conflicted files to Claude Code before it opens the\npull request. It is off until you add a variable and a secret:",[366,1040,1041,1053],{},[369,1042,1043],{},[372,1044,1045,1048,1051],{},[375,1046,1047],{},"Name",[375,1049,1050],{},"Kind",[375,1052,377],{},[382,1054,1055,1070,1083],{},[372,1056,1057,1062,1065],{},[387,1058,1059],{},[173,1060,1061],{},"KIT_UPDATE_RESOLVER",[387,1063,1064],{},"variable",[387,1066,1067],{},[173,1068,1069],{},"claude",[372,1071,1072,1077,1080],{},[387,1073,1074],{},[173,1075,1076],{},"ANTHROPIC_API_KEY",[387,1078,1079],{},"secret",[387,1081,1082],{},"An Anthropic API key, billed to that API account.",[372,1084,1085,1090,1092],{},[387,1086,1087],{},[173,1088,1089],{},"CLAUDE_CODE_OAUTH_TOKEN",[387,1091,1079],{},[387,1093,1094,1095,1098],{},"Instead of the key: a token from ",[173,1096,1097],{},"claude setup-token",", billed to that person's Claude subscription.",[169,1100,1101,1102,1105,1106,1109,1110,1113],{},"The secrets alone never turn it on. Two optional variables tune it:\n",[173,1103,1104],{},"KIT_UPDATE_RESOLVER_BUDGET"," caps each run at that many US dollars of Claude's\nown estimate, ",[173,1107,1108],{},"5"," when it is not set, and ",[173,1111,1112],{},"KIT_UPDATE_MODEL"," picks the model.\nClaude is billed only when an update has a conflict.",[169,1115,1116],{},"Claude Code gets the conflicted files only, with the kit's old and new version\nand your version of each beside them. It can read and edit files in the\ncheckout and nothing else: no shell, no web, no GitHub token. It is never given\nthese, which keep their conflicts for you or are settled by the workflow:",[512,1118,1119,1129,1140,1150,1154],{},[197,1120,1121,1122,619,1125,1128],{},"anything in ",[173,1123,1124],{},"layers\u002Fkit\u002F",[173,1126,1127],{},".github\u002F",";",[197,1130,1131,1133,1134,619,1137,1128],{},[173,1132,821],{},", or a ",[173,1135,1136],{},"wrangler.json",[173,1138,1139],{},"wrangler.toml",[197,1141,1142,535,1144,535,1146,1149],{},[173,1143,676],{},[173,1145,679],{},[173,1147,1148],{},".npmrc"," and a pnpmfile;",[197,1151,1152,1128],{},[173,1153,208],{},[197,1155,1156],{},"a binary file: when both sides changed one, your version is kept, and\nmerging drops the kit's change to it for good.",[169,1158,1159,1160,1163,1164,1166,1167,1170],{},"The workflow checks its work before keeping any of it. If Claude edits a file\nit was not given, none of its work is kept. It cannot write to ",[173,1161,1162],{},".git\u002F",", and if\nGit's config, attributes or hooks change anyway, the run stops and pushes\nnothing. A file it was unsure of, left markers in, or wanted to delete although\nboth sides changed it goes back the way the update left it, for you to settle.\nWhen Claude resolved ",[173,1165,673],{},", nothing it chose runs before you have read\nit, so the resolved files are left unformatted: run ",[173,1168,1169],{},"pnpm format"," on the branch\nif CI asks for it.",[169,1172,1173,1174,1176,1177,1180,1181,1183],{},"Each file's row in ",[252,1175,783],{}," says what Claude did and how sure it was. A\npull request with conflicts Claude resolved is never green. It is ",[252,1178,1179],{},"Read before\nmerging",", or ",[252,1182,791],{}," when something else still needs you. Its\nmerge is a proposal, and merging deploys it.",[189,1185,1187],{"id":1186},"your-tests-on-the-pull-request","Your tests on the pull request",[169,1189,1190],{},"The pull request runs your CI once, like any other, and so does any workflow\nyour organization requires on every pull request.",[169,1192,1193,1194,1197,1198,1201,1202,1204,1205,1207,1208,1211,1212,1214,1215,1217,1218,1002],{},"In an app, a plain ",[173,1195,1196],{},"pnpm test"," runs what your CI runs: your own suites and the\nkit suites that check your files and config. The kit's other suites test the\nconfig the kit ships, so they fail in an app that changed it for reasons that\nare not yours. ",[173,1199,1200],{},"pnpm test:e2e"," likewise runs only your own Playwright specs.\nThe kit tells an app from itself by ",[173,1203,208],{}," at the root, so a test\nworkflow of your own that runs ",[173,1206,1196],{}," runs the same suites your CI\ndoes. ",[173,1209,1210],{},"KIT_SUITES=all pnpm test --run"," still runs every kit suite. An app that\nhas not taken its first update has no ",[173,1213,208],{}," yet, and until then\n",[173,1216,1196],{}," runs everything (",[182,1219,1221],{"href":1220},"\u002Fdocs\u002Ftesting","Testing",[189,1223,477],{"id":1224},"when-a-run-fails",[169,1226,1227],{},"A run fails when someone has to act, and GitHub emails whoever started it or\nlast changed its schedule. The run's summary opens with the reason:",[366,1229,1230,1239],{},[369,1231,1232],{},[372,1233,1234,1237],{},[375,1235,1236],{},"The run says",[375,1238,749],{},[382,1240,1241,1254,1267,1280,1306,1322,1335,1345,1360,1372,1385,1398],{},[372,1242,1243,1248],{},[387,1244,1245],{},[173,1246,1247],{},"The KIT_UPDATE_TOKEN secret is not set.",[387,1249,1250,268],{},[182,1251,1253],{"href":1252},"#add-it-to-your-app","Add it",[372,1255,1256,1261],{},[387,1257,1258],{},[173,1259,1260],{},"GitHub refused KIT_UPDATE_TOKEN: it has expired or was revoked.",[387,1262,1263,1264,1266],{},"Create a new token and replace the secret's value. ",[173,1265,552],{}," can say the same.",[372,1268,1269,1274],{},[387,1270,1271],{},[173,1272,1273],{},"KIT_UPDATE_TOKEN cannot see …",[387,1275,1276,1277,1279],{},"Give the token access to this repository. A fine-grained token needs it in its list and, if it targets an organization, an owner's approval: until then it reads public repositories only. A classic token needs the ",[173,1278,295],{}," scope and an account that can open the repository.",[372,1281,1282,1287],{},[387,1283,1284],{},[173,1285,1286],{},"… cannot read nuxter-app\u002Fkit",[387,1288,1289,1290,1292,1293,1295,1296,1298,1299,1301,1302,268],{},"Set ",[173,1291,552],{}," to a token that can read the kit (",[182,1294,499],{"href":312},"): a fine-grained ",[173,1297,342],{}," never can, and a fine-grained ",[173,1300,559],{}," token may still wait for an owner's approval. If your account lost access, see ",[182,1303,1305],{"href":1304},"#losing-access-to-the-kit","Losing access to the kit",[372,1307,1308,1313],{},[387,1309,1310],{},[173,1311,1312],{},"… changes a workflow file …",[387,1314,1315,1316,1318,1319,268],{},"Tick ",[173,1317,299],{}," on a classic token, or give a fine-grained one ",[252,1320,1321],{},"Workflows: Read and write",[372,1323,1324,1332],{},[387,1325,1326,619,1329],{},[173,1327,1328],{},"… needs Contents: read and write",[173,1330,1331],{},"… needs Pull requests: read and write",[387,1333,1334],{},"Give the fine-grained token that permission.",[372,1336,1337,1342],{},[387,1338,1339],{},[173,1340,1341],{},"KIT_UPDATE_CHANNEL is …; set it to main, release or off.",[387,1343,1344],{},"Fix the variable's value.",[372,1346,1347,1353],{},[387,1348,1349,1352],{},[173,1350,1351],{},"layers\u002Fkit\u002F differs from the template's … in:"," and a list of files",[387,1354,1355,1356,1002],{},"Move each change into a file of yours (",[182,1357,1359],{"href":1358},"\u002Fdocs\u002Ftemplate#a-changed-layerskit-is-refused","A changed layers\u002Fkit\u002F is refused",[372,1361,1362,1367],{},[387,1363,1364],{},[173,1365,1366],{},"No template commit matches this app’s first commit …",[387,1368,1369,1370,268],{},"Run the workflow by hand with the kit commit or tag your app started from in ",[686,1371,637],{},[372,1373,1374,1379],{},[387,1375,1376],{},[173,1377,1378],{},"A file and a folder clash at …",[387,1380,1381,1382,1384],{},"Take this update with ",[173,1383,179],{}," by hand and settle it there.",[372,1386,1387,1392],{},[387,1388,1389],{},[173,1390,1391],{},"The kit-update branch has commits that are not the workflow's …",[387,1393,1394,1395,1397],{},"Rename or delete your ",[173,1396,175],{}," branch: the workflow needs that name.",[372,1399,1400,1405],{},[387,1401,1402],{},[173,1403,1404],{},".template-base names …, which nuxter-app\u002Fkit no longer has …",[387,1406,1407,1408,1410,1411,1413],{},"Run the workflow by hand with the kit commit or tag in the kit's current history that matches the one your app last took in ",[686,1409,637],{},". The hash in ",[173,1412,208],{}," is no longer in the kit, so the run refuses it.",[169,1415,1416,1417,1419],{},"When the kit's history is rewritten and the run can find the kit commit that\nmatches your ",[173,1418,1124],{},", it uses that one and says so in the pull request\ninstead of failing. A run that changed nothing for a reason that needs no one,\nsuch as an update whose pull request you closed or your default branch moving\nwhile it worked, ends green with a notice.",[169,1421,1422],{},"A GitHub outage is one of those reasons. When a read from GitHub's API meets an\nerror on GitHub's side, or cannot reach GitHub, the run tries it again after 3\nand then 10 seconds. If GitHub still fails while the run first reads your app,\nthe kit and their pull requests, or fetches from them, the run stops before it\nhas changed anything. Its notice says the problem is GitHub's, not a token's,\nand the next run tries again. An outage later in the run fails it like any\nother error.",[189,1424,1305],{"id":1425},"losing-access-to-the-kit",[169,1427,1428,1429,1431,1432,1435,1436,1439,1440,1442,1443,268],{},"The workflow reads ",[173,1430,258],{}," with your token, as ",[173,1433,1434],{},"git fetch template","\ndoes on your machine. If the account behind the token was removed from the kit\nrepository, every run fails with\n",[173,1437,1438],{},"KIT_UPDATE_TOKEN cannot read nuxter-app\u002Fkit (GitHub answered 404)",", or names\n",[173,1441,552],{}," when that one reads the kit. If the token belongs to someone\nwho left your team and also lost your app's repository, the run usually stops\none step earlier, at your own repository, with\n",[173,1444,1273],{},[169,1446,1447,1448,426,1450,1452],{},"Your app keeps working and keeps every update it already took: only new\nupdates stop. Replace the secret with a token from an account that can read\nthe kit and your app, or set ",[173,1449,363],{},[173,1451,417],{}," to stop the daily\nfailures.",[189,1454,1456],{"id":1455},"good-to-know","Good to know",[512,1458,1459,1466,1484,1503,1510],{},[197,1460,1461,1462,1465],{},"A run that finds nothing new takes about a minute of Actions time. A run\nthat opens a pull request takes a few, and the pull request then runs your\nCI once. The branch is built again only for the reasons in\n",[182,1463,647],{"href":1464},"#what-each-run-does",", so a busy kit does not mean a busy\napp.",[197,1467,1468,1469,1472,1473,1476,1477,1479,1480,1002],{},"In a monorepo folder the workflow does not run: GitHub reads workflows only\nfrom the repository root's ",[173,1470,1471],{},".github\u002Fworkflows\u002F",", and a copy moved there\nfails, because its step runs ",[173,1474,1475],{},"layers\u002Fkit\u002Fscripts\u002Ftemplate\u002Fpropose.mjs"," from\nthe root. Take updates with ",[173,1478,179],{},"\n(",[182,1481,1483],{"href":1482},"\u002Fdocs\u002Ftemplate#apps-in-a-subfolder","Apps in a subfolder",[197,1485,1486,1488,1489,1491,1492,1495,1496,1499,1500,1502],{},[173,1487,175],{}," is the workflow's branch name. Name a branch of your own\nanything but ",[173,1490,175],{}," or a name under ",[173,1493,1494],{},"kit-update\u002F",", which makes the\nrun's push fail. The ",[173,1497,1498],{},"kit-update-\u003Cdate>"," that\n",[182,1501,1001],{"href":1000}," suggests is fine.",[197,1504,1505,1506,1509],{},"The workflow lives in your app's ",[173,1507,1508],{},".github\u002Fworkflows\u002Fkit-update.yml",", which the\nkit owns, so kit updates bring its changes too.",[197,1511,1512,1513,1516],{},"Every action the workflow uses runs at a fixed commit, never a release tag\nsuch as ",[173,1514,1515],{},"actions\u002Fcheckout@v7",". Whoever controls an action's repository can\nmove a tag to new code, which would then run in the job that holds your\ntokens. The kit's other workflows pin theirs the same way, so a newer release\nof an action reaches your app as a kit update that changes workflow files.",[1518,1519,1520],"style",{},"html pre.shiki code .snPdu, html code.shiki .snPdu{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sIIMD, html code.shiki .sIIMD{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sBjJW, html code.shiki .sBjJW{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#79B8FF}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);}",{"title":912,"searchDepth":17,"depth":17,"links":1522},[1523,1524,1532,1533,1534,1537,1538,1539,1540,1541,1542],{"id":191,"depth":17,"text":192},{"id":235,"depth":17,"text":236,"children":1525},[1526,1527,1528,1529,1530,1531],{"id":243,"depth":22,"text":244},{"id":317,"depth":22,"text":318},{"id":349,"depth":22,"text":350},{"id":437,"depth":22,"text":438},{"id":481,"depth":22,"text":482},{"id":498,"depth":22,"text":499},{"id":575,"depth":17,"text":576},{"id":646,"depth":17,"text":647},{"id":727,"depth":17,"text":728,"children":1535},[1536],{"id":894,"depth":22,"text":895},{"id":1005,"depth":17,"text":699},{"id":1034,"depth":17,"text":1035},{"id":1186,"depth":17,"text":1187},{"id":1224,"depth":17,"text":477},{"id":1425,"depth":17,"text":1305},{"id":1455,"depth":17,"text":1456},[1544,1545],{"path":24,"title":25,"description":26,"navTitle":25,"group":6,"order":27},{"path":34,"title":35,"description":36,"navTitle":35,"group":6,"order":37},false]