aws-amplify / aws-amplify/amplify-cli
Improve Current Messed Up Functions Directory Structure and Build Process (NodeJS)
- Dominant language
- TypeScript
- Stars
- 2.9k
- Forks
- 825
- Avg merge
- 11d 23h
- Merged PRs (30d)
- 2
Description
**Is your feature request related to a problem? Please describe.**
Current NodeJS function's directories structure is very confusing and, at least, unconventional.
At the moment, `package.json`, `node_modules` and other similar files/directories are weirdly located inside the `src` directory. Generally, this files are found under a package's root directory.
I know that the whole thing must then be converted into a deployment package and that the task might be simplified by having everything under a single directory, but the current structure is very confusing and especially complicated when building process customization is involved. Indeed, I've followed [Functions - Build Options](https://docs.amplify.aws/cli/function/build-options) guide and it complicates things even more.
Again, in general, a `src` directory is used to only contain our written and un-compiled code. Successively, `lib`, `dist` and/or `build` directories are commonly used to store compiled and/or bundled code. These last directories should be considered 'volatile' and should not be manually modified.
The above mentioned guide mixes everything without any kind of consideration. It pretends us to have an empty `src` directory (containing just the `package.json`) and a `lib` directory containing all the un-compiled (source) code (?). Without mentioning that the idea of having a `amplify:` script in the root `package.json` for every function is insane.
This are some additional issues for this pattern:
1. Source code, now inside `lib` directory has no associated `package.json` file and `node_modules` directory for used modules to be resolved. So, type checking and other coding assistance breaks.
2. Code cleanup is not considered for compiled code now inside `src` directory. This means that generated files will replace existing matching files, but new added files or renamed ones will leave the old files inside the `src` directory.
3. The adopted convention is almost the inverse of a normal project convention.
**Describe the solution you'd like**
I would suggest to adopt a more standard directory structure by placing `package.json`, `node_modules` and other similar files/directories in the function's package root directory and to leave the `src` directory for source code only (initially the `index.js` file), adjusting `package.json` `main` and `module` properties accordingly. Maybe use `directories` and `files` properties like NPM does for defining/filtering what should end inside the final deployment package.
Custom build process could be defined inside the function's `package.json` and not in the project root. `babel --root-mode upward ./src --out-dir ./lib --copy-files` would allow to use a `babel.config.js` file in the project's root. Even per-function local configurations or local installations of devDependencies could be allowed.
Compiled code (EX: Babel output) could be placed inside a `lib` (or other) directory and Amplify should build the deployment package using the `package.json` `files` and `directories` properties as described above.
There are so many possible combinations. I think it can not be worse than it currently is.
**Describe alternatives you've considered**
I've currently followed the above guide and additionally copied the `package.json` file to the `lib` directory and set Babel to ignore `node_modules`. I'm not happy with the current structure and suggested pattern.
**Additional context**
None.
Contributor guide
Research direction
Read the Functions - Build Options guide and inspect how function package.json, src, lib, node_modules, and the project-root babel.config.js are currently used. Define a standard function layout and build contract, including where source and compiled files belong and how the deployment package is selected; done means the structure and customization path are documented and consistently supported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- babel, nodejs
- Domain
- build-system, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100