Fix the Monorepo documentation

[craggy zodiac]

The documentation at https://docs.amplify.aws/nextjs/deploy-and-host/fullstack-branching/monorepos/ seems incomplete and confusing.

1. The screenshot under Deploy backend app has text shared-backend in the "monorepo root directory" box. Which seems incorrect as the path to the backend project according to the example should be packages/my-shared-backend (IIUC).
2. It says the build settings would be automatically detected. However, it thinks the backend is a "next.js" project, where as it only has Amplify generated code. It would be good to elaborate what to expect on this page. The page populates a "Front end build command" and a "build output directory". This is confusing as this is amplify code only. What should the build commands be, for this project?
3. Also, please provide some context as to why we need to use "ampx generate outputs" command in a monorepo
4. How do we test the app in a sandbox when the app is in a monorepo?

[hoary ginkgo]

1. You are correct. 2. As far as I'm aware amplify gen 2 has no distinction between a front end app and a backend app so when creating your backend app for your mono repo create a dumby / filler build command as seen here https://docs.amplify.aws/react/deploy-and-host/fullstack-branching/mono-and-multi-repos/. (eg. build: mkdir ./dist && touch ./dist/index.html output: dist (also please note when initlizing the project in the console you should see amplify gen 2 as the framework not next js) 3. The ampx generate outputs command is important for the deployment because it tells amplify which resources need to be built for your backend to work. If you're creating a backend app amplify needs to know what resources it needs to build. If you're creating a frontend app you need to use the generate command ampx generate outputs --branch $branch --app-id $app-id to point your front end app to your backend app resources. 4. you can use the sandbox locally by navigating to your backend directory in a seperate shell to your frontend app in your project and run ampx sandbox. This will create a entirely isolated resource stack from your deployment stack that will allow you to test. General Comments: The documentation is not great for gen 2 at the moment and I had to trial and error lots of times to get it to work.

[craggy zodiac]

@hoary ginkgo Thank you for the dtailed answer! This extremely helpful.

[craggy zodiac]

Regarding:

(also please note when initlizing the project in the console you should see amplify gen 2 as the framework not next js)
I believe it might be tracking back to the main package.json file in the root of the monorepo where it would find next.js libraries.

So, in which case, I wonder if the ideal structure for the monorepo is not

|- apps/
     |- app1
     |- app2
|- libs/
     |-backend
|- package.json

But, have the projects be completely independenat

|- apps/
     |- app1
     |- app2
     |- package.json
|- libs/
     |-backend
     |- package.json

[hoary ginkgo]

My mono repo project structure looks like this as in line with the recommendations from the amplify gen 2 docs

/ (root)
|- package.json          # Root package.json, handles scripts and maybe common dev dependencies
|- apps/
   |- app1/
      |- src/
      |- package.json    # package.json for app1 specific dependencies
   |- app2/
      |- src/
      |- package.json    # package.json for app2 specific dependencies
|- libs/
   |- backend/
      |- amplify/        # AWS Amplify Gen 2 configuration
      |- package.json    # package.json for backend specific dependencies

I use pnpm workspaces as my package manager but this will generally work with others such as npm (i'd probably stay away from yarn workspaces personally)

[craggy zodiac]

hmm.. in which case, I'm confused as to why my Amplify console identify the framework as Next.js instead of Amplify Gen 2

Do you mind sharing your /libs/backend/package.json file?

[hoary ginkgo]

Here is the package.json

{
  "name": "backend",
  "type": "module",
  "scripts": {
    "build": "mkdir ./dist && touch ./dist/index.html"
  },
  "devDependencies": {
    "@aws-amplify/backend": "^1.0.3",
    "@aws-amplify/backend-cli": "^1.0.4",
    "@aws-lambda-powertools/logger": "^2.1.0",
    "@types/aws-lambda": "^8.10.137",
    "aws-cdk": "^2.141.0",
    "aws-cdk-lib": "^2.141.0",
    "constructs": "^10.3.0",
    "esbuild": "^0.21.1",
    "tsx": "^4.9.3",
    "typescript": "^5.4.5"
  },
  "dependencies": {
    "aws-amplify": "^6.3.6",
    "aws-sdk": "^2.1585.0",
  }
}

Here is my amplify.yml for my backend amplify gen 2 app in the amplify console

version: 1
applications:
  - backend:
      phases:
        build:
          commands:
            - rm -rf node_modules
            - corepack enable
            - pnpm install --frozen-lockfile
            - pnpm exec ampx generate outputs --branch $AWS_BRANCH --app-id $AWS_APP_ID
            - bash scripts/copyPackages.bash
            - pnpm exec ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID
    frontend:
      phases:
        build:
          commands:
            - mkdir ./dist && touch ./dist/index.html
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      buildPath: packages/backend
    appRoot: packages/backend

Please also note I keep my non-app packages under /packages instead of /libs as we've discussed in previous examples (ie. my amplify folder lives in packages/backend/amplify)

[hoary ginkgo]

Make sure you're setting your monorepo app root to libs/backend when making the project in the console. You should init your amplify project using npm create amplify@latest inside the libs/backend folder so that all the relevant packages are added to that package.json

[craggy zodiac]

I'm using NX and in a new repo, I tried out multiple configurations and was able to get Amplify Console to identify the framework correctly. However, even copying over the same same package.json from the working configs to the original repo, only caused it to detect multiple frameworks, which is wierd.

But, that's fine. I can reset that repo and start again because I tried this before writing any code.

[hoary ginkgo]

That's great news! Just looking at your build output directory there you have set as .next As you can see in my amplify.yml I've got mine set to the backend directory (in your example libs/backend). I wonder if that would have anything to do with it? to be honest I've given up on gen 2 for the time being. I believe it's far to unstable to build for production at the moment. I'm looking forward to using it in the future though.