Revising the template structure

[halfzebra]

After the discussion in elm-community Slack channel, @eeue56 pointed out, that Create Elm App does not follow the common consensus on the application template structure.

Structure variations

Current

my-app/
  .gitignore
  README.md
  elm-package.json
  src/
    App.elm
    favicon.ico
    index.html
    index.js
    main.css
  tests/
    elm-package.json
    Main.elm
    Tests.elm

elm-community consensus

my-app/
  site/
      favicon.ico
      index.html
      index.js
      main.css
  elm/
    .gitignore
    README.md
    elm-package.json
    src/
      Main.elm
    tests/
      elm-package.json
      Main.elm
      Tests.elm

Introduced in #124

my-app/
|-- public/ # or site
|   |-- css/
|   |    `- main.css
|   |-- js/
|   |    `- index.js # or main.js
|   |-- media/
|   |    `- logo.svg
|   |-- favicon.ico
|   `-  index.html
|-- src/ # or elm (elm/src seems a bit much)
|   `- App.elm
|-- test/
|   |-- Main.elm
|   |-- Tests.elm
|   `-  elm-package.json
|-- .gitignore
|-- README.md
`-  elm-package.json

The problem

The current structure does not offer a way to handle static assets when a user wants to have static media assets, which are not referenced in index.js

Create React App offers the public folder, as a place for static assets. It also contains index.html, which is included into the webpack process.

The structure offered in #124 makes it harder for us to use public/ folder for static assets, in the way it was implemented in CRA. Also it does not allow us to implement the structure, offered by elm-community.

We also need to have in mind, that #134 will introduce the file or folder for elm-css stylesheets.

#124 will introduce a breaking change to Create Elm App, so we have to agree on the future structure, so it follows the community desires and allows having static content outside the module system(i.e. outside the webpack build)

@fobos @MazeChaZer @lrosa007 Please share your thoughts, I'll pitch this issue in elm-community as well.

• Moving index.html and favicon.ico to /public
• Main.elm vs. App.elm
• Moving index.js to /public

[rvcas]

Cool, thanks for the write up and merging related but spreadout issues/PRs. I'll take some time to think and post later with some thoughts.

[MazeChaZer]

@halfzebra Thanks for starting this discussion and pinging me

I actually had a problem with the current directory structure in my project. I wanted to use CKEditor within my Elm app (embedding via web components works surprisingly well). I couldn't just import it via webpack because they are doing some magic during the initialization like manually loading CSS and localization files. So I just wanted to drop it into the src/ folder next to the index.html and include it using a <script> tag. Unfortunately that didn't work. I use their public CDN for now but that isn't optimal. I previously started to develop a React prototype for the same project where I used create-react-app and there I could just drop it into the public directory.

Long story short, I think it is important to have a public/site folder that contains the static assets and a separate folder for the Elm source files. I think the proposed elm-community consensus goes into the right direction. I just personally find it a little strange that there is an elm/ subfolder. I would just put the content of elm/ into the root directory.

[rvcas]

@MazeChaZer I agree, the elm/src/Main.elm seems excessive. Oh also, looking at the examples again, the alignment is a little off on the example from #124. When the alignment is proper, you'll see some similarities between the elm-community approach and the approach that came about in #124.

@halfzebra Also, I'm not super adamant about the sub-nesting of file types in public (css/ & js/ & media). We can kill the sub-nesting now if all those concerned aren't happy with it thus making it even more similar to the elm-community approach. So correcting the alignment in your post for the #124 approach and adding comments with the names from the elm-community approach results in:

my-app/
|-- public/ # or site
|   |-- css/
|   |    `- main.css
|   |-- js/
|   |    `- index.js # or main.js
|   |-- media/
|   |    `- logo.svg
|   |-- favicon.ico
|   `-  index.html
|-- src/ # or elm (elm/src seems a bit much)
|   `- App.elm
|-- test/
|   |-- Main.elm
|   |-- Tests.elm
|   `-  elm-package.json
|-- .gitignore
|-- README.md
`-  elm-package.json

So two questions:

1. What do we name the folders (site or public)? (no preference on my part)
2. Is there a good reason to nest everything else within another folder named elm?

My thoughts on two:

We can move everything that would be in the elm directory up a level. Then on to litigating whether or not we call the primary elm source code folder src or elm (see question 1).

Note

That all being said, I have not thought about how any of that affects #134.

[halfzebra]

@lrosa007 My bad, thanks for pointing out!

#124 is definitely a step in the right direction, I have updated the example with the original comment.

Clearly, offered structure by the elm-community does not take into account a lot of aspects.

We can look at elm-community/elm-webpack-starter for inspiration.

The folder name is most likely public

elm/ is containing all of the Elm code, not everything goes there.

Could you please give an example of the structure from the last thought?

We can move everything that would be in the elm directory up a level. Then on to litigating whether or not we call the primary elm source code folder src or elm (see question 1).

[rvcas]

@halfzebra of course, no problem.

so without the double nesting thing:

my-app/
|-- public/ # IMPORTANT (site)
|   |-- css/
|   |    `- main.css
|   |-- js/
|   |    `- index.js # or main.js
|   |-- media/
|   |    `- logo.svg
|   |-- favicon.ico
|   `-  index.html
|-- elm/ # IMPORANT (used to be src)
|   `- App.elm
|-- test/
|   |-- Main.elm
|   |-- Tests.elm
|   `-  elm-package.json
|-- .gitignore
|-- README.md
`-  elm-package.json

Instead of my-app/elm/src/Main.elm that example ends up as my-app/elm/App.elm. Oh also I have no preference for calling the primary elm file Main or App, if that even matters 👍

[MazeChaZer]

I would personally prefer Main over App because this seems to be the standard in the Elm guide and other Elm boilerplate projects:

• https://guide.elm-lang.org/interop/javascript.html
• https://guide.elm-lang.org/reuse/modules.html
• https://github.com/elm-community/elm-webpack-starter/tree/master/src/elm
• https://github.com/gkubisa/elm-app-boilerplate/tree/master/elm
• https://github.com/fluxxu/elm-hot-loader-starter/tree/master/src
• https://github.com/splodingsocks/elm-starter/tree/master/src
• https://github.com/Gizra/generator-elmlang/tree/master/generators/app/templates/src/elm

Additionally, Main is the implicit module name if the module decaration in an Elm file is omitted.

[joakin]

I believe with #123, create-elm-app/template/README.md#folder-structure is outdated as it shows index.html and the favicon in src/.

[halfzebra]

It seems like most of the concerns have been addressed so I'm closing this.