1.0.0

[bloodyowl]

hi people!

we discussed a lot with @MoOx in the last few weeks, about the current limitations of the solutions and requests you made. I started prototyping a few things and I'm proud to say that the 1.0.0 version will be ready soon. in short, what you should know:

• we are not going to rely on Next for now
• phenomic will have a much better CLI (with one line install)
• phenomic will not bring all the pages metadata in all pages anymore, scalability is at the core of our preoccupations
• phenomic will be modular
  • it's not going to rely on webpack to grab content anymore, it's going to be using watchman, leveldb and express under the hood
  • the phenomic api will be extensible with plugins
  • plugins can be put in presets (like babel)
• phenomic will handle pagination

sneak peeks

phenomic-plugin-react query

modular!

output

[MoOx]

😱 Can't wait for the PR

For anyone reading this, feel free to share all your thoughts and questions so we can be sure to address everything.

[VinSpee]

Looking amazing!

• Is this still going to use redux with phenomic's collentionEnhancer?
• is it going to continue to use react-router w/ the concept of PageContainer?

Those are two pain-points I have and would love for them to be simplified in some way.

Thanks for the great work, looking forward to upgrading.

[bloodyowl]

@VinSpee

Is this still going to use redux with phenomic's collentionEnhancer?

redux will not be used by default, but as it's going to be modular, you can build a plugin that uses it if you want. enhanceCollection will not be here anymore, the query utility you can use in the higher-order-component will do this just as well

react-router will be kept for now, although there are some complications with where there are going for v4, mainly because the new API doesn't let us analyse routes statically (which we really need to do). we're going to stick with it for now and see what happens next.

the PageContainer will disappear for a simple Renderer. we are going to release a plan to upgrade real soon, and it will be real simple 😊

[VinSpee]

That all sounds fantastic. I'm excited about the direction phenomic is taking! Thanks again!

[thangngoc89]

Will there be any boilerplate code? Do I have to change a lot of code for upgrading ? (I mean from 1.0.0 and beyond)

[bloodyowl]

What changes:

The content directory root lists collections, for instance:

- content
  - authors
  - blog
  - pages
  - faq

will produce 4 collections: authors, blog, pages & faq. in these directories you can organise as you want.

it's you who decides of URL behaviour in your routing, for instance:

<Route path="/" component={Home} />
<Route path="/blog" component={BlogList} />
<Route path="/blog/post/*" component={BlogPost} collection="blog" />
<Route path="/faq" component={FAQList} />
<Route path="/faq/item/*" component={FAQList} collection="faq"/>
<Route path="/404.html" component={Error404} />
<Route path="*" component={Page} collection="pages" />

In your root components, you can do this to express your data requirements:

module.exports = createContainer(BlogList, {
  posts: query({
    collection: "blog",
  }),
  tags: query({
    collection: "tags",
    filter: "blog",
  }),
})

The only boilerplate you need is to use this as an entry point:

import { Renderer } from "phenomic-react/lib/client"

const app = (
  <Router>
    {/* your routes*/}
  </Router>
)

module.exports = Renderer.render(app)

[VinSpee]

this looks absolutely brilliant. Thanks!

[ryandeussing]

I build a lot of static sites using Jekyll et al and I'm starting to get excited by SPA approaches. Like @brianrc I'd really appreciate a breakdown of the differences between Next.js and Phenomic. I'm trying to determine if one or the other is a good/better fit for statically-served, SPA sites powered by something like NetlifyCMS or Contentful.

I also see some discussion of Phenomic possibly adopting Next.js, so any updates on that would be very helpful as well.

Thanks for any insight you can share!

[kennu]

This looks really exciting. I have been struggling a bit with porting my ~2000 content page website to Phenomic. All kinds of problems happen when building it and development mode is slow.

I hope my page structure will work with the new version. It's like this:

content/<manufacturer>/index.md - Manufacturer page (layout: Manufacturer)
content/<manufacturer>/<product>.md - Product page (layout: Product)

That makes it easy to associate products relationships with manufacturers without adding any extra fields, just by putting them in the right subfolders. I wouldn't mind getting rid of the repetitive layout: fields in all pages though.

[ivan-kleshnin]

@bloodyowl

phenomic will be modular
it's not going to rely on webpack to grab content anymore, it's going to be using watchman, leveldb and express under the hood

Are LevelDB and Express are going to be used only for development stage?

Otherwise, I don't understand what is "static" about Phenomic.
It's rather an app skeleton or a demo app, than a site generator.

[bloodyowl]

@brianrc @ryandeussing next needs a server-side runtime, Phenomic doesn't, it's a static site generator.

@kennu This use case is interesting, I'll make the collection resolver customisable for this kind of needs.

@ivan-kleshnin These dependencies are only used during development & build

[thangngoc89]

@ivan-kleshnin Phenomic is a static site generator. It doesn't require any server code to run. And you are right, LevelDB and Express are used for development. Express is used since the first version of Phenomic.
@bloodyowl do you have any plan that support generating a site from external data (rest api, graph api,...) without writing a script to generate markdown files from these data first?

[ryandeussing]

I am thinking about rewriting Phenomic using Next.js. [#889]

Sorry to have skated around my question, which is: if this is not happening for 1.0, is it still being considered? Thx.

[bloodyowl]

no, given the shift in modularity it is not an option anymore

[kennu]

Thanks @bloodyowl. I guess my desired use case can be generalized into supporting folder structures, so all 2000 pages don't have to be in one flat folder. The "special" thing is the index.md of each folder, so I can maintain URL structure /manufacturer/ for manufacturers and /manufacturer/product/ for products. I hope it can somehow fit the route definitions.

[ivan-kleshnin]

@bloodyowl @thangngoc89 ok, thanks for clarifications. I'm looking forward for this new version with other people :)

[revolunet]

Hey hey, good to know things are moving forward :)

What to you mean by "soon" for a first RC ? 😄

how do you plan handling .json files or 3rd party data sources ?
for example, some "collection" may come from a single json, or a 3rd party db

Tell me if theres any phenomic sprint around :)

[bloodyowl]

I'm currently adding static types (flow) to the prototype I've got, the last big step before an alpha version is decoupling the content fetcher, making it a plugin so that any type of source can work

[thangngoc89]

@bloodyowl that's awesome. Decoupling the content fetcher is a must. I need more than 1-to-1 map between markdown files and pages.

[thangngoc89]

@bloodyowl from what I understand, phenomic-react is a plugin which generates a React powered site with Phenomic. If I want to generate an AMP version of the same content, I could write a phenomic-amp plugin is do that write?

[AdrianoCahete]

I'm landing on this project now: Searching for static site generator, from reddit.
Reading issues to know if have any problem for my development, i find this issue.

it's going to be using watchman, leveldb and express under the hood

Since the actual version works, the 1.X version will work on Windows? Because watchman is in alpha phase now...

[brianrc]

eek, I'm also on Windows...

[MoOx]

Windows will be supported on the medium/long run, don't worry. We will look how other projects handle this (like flow and react-native - which works on windows for a while)

[bloodyowl]

we'll add chokidar as a fallback

[MoOx]

sane is maybe a better option

[DavidWells]

@bloodyowl what is the ETA on seeing this branch? No rush of course!

I'm just trying to plan out some stuff for our site and am very curious to see + collaborate on the upcoming version.

We have a very serious need to solve some of the looming issues the current version has in regards to supporting larger sites (1000+ pages) and I'd like to help anywhere I can on this!

Thanks! ⊂◉‿◉つ

[MoOx]

I hope to have some time next week (if my life can go back to normal - which isn't the case for the past 3 weeks) to make a feature list and prepare the new branch so we can start opening a usable PR before the end of the month.

[bloodyowl]

Here is the WIP: https://github.com/bloodyowl/PhenomicFuture
Doesn't fully work yet, but should be an interesting sneek peak.
I know the commit history is a total mess, sorry about that 😅
This way it'll be easier for everyone to track changes and coordinate.

[MoOx]

@bloodyowl let's have a chat asap to start a PR with your work.
I will try to get some time this evening (the sooner the better - I will poke you around)

My idea is (since it's a complete reboot):

• cut a branch on this repo
• add your code in a PR, but do not remove anything of the existing repo (should be ok since you place most of the code in "packages", I don't see major conflicts here)
• open a PR
• add a basic migration guide (even if wip) - so we and anyone can start play with it
• remove old code that have it's counter part in the new codebase + add migration instructions if relevant
• only remove old code when similar feature is implemented in new codebase OR if we decide to remove some. Again, anything change should be mentioned a migration guide)

Tell me if this approach looks good to you. I am starting a checklist anyway.

[MoOx]

⚠️ This list is a total mess for now as I just read the entire source code and listed what I see we should have

• webpack can be boosted with hard source plugin (cache)
• internal links from markdown are not doing full page load, but caught and leveraging phenomic optimistic loading (note that “internal” but not unknown links (eg: /project/static-but-not-handled-by-phenomic.html) are not caught. (see src/_utils/catch-links)
• src/_utils/error-formatter transform errors to make those more readable (adjust path + remove useless stuff)
• (terminal) logs are created using a single module for coherence (src/_utils/log + src/builder/log-formatter)
• url + pathname for the website is defined once via the full website url (http://example.com/root/)
• offline options to enable service worker (for now via offline-plugin) that auto-register content
• scripts in markdown (json) are correctly escaped (src/_utils/serialize) to avoid json parsing issues
• one util transform all the paths to uri and remove extension like .md/txt/asciidoc etc (src/_utils/urlify)
• webpack 1 and 2 are supported (but I guess webpack 2 can be the only one - not a lot of changes anyway)
• works on windows (it’s a feature yeah)
• src/bin/check-engine check that you use the correct node/npm/yarn version before executing phenomic job (to avoid issue on github etc)
• $ phenomic start
• $ phenomic build
• $ phenomic setup: ask questions to create your config and copy the base theme
• some const PHENOMIC_* are injected during the build (src/builder/config.common.js)
• sourcemap works out of the box during development, even for static build that use webpack build for node build (🙃)
• phenomic check webpack config to avoid error
• an “assets” folder can be copied from “content” folder - not sure this make sense with the new architecture - but people should be able to reference assets from markdown and that should work “as expected”
• phenomic open project in a tab when you “start” and reuse an existing chrome tab if already open (src/builder/openChrome)
• postbuild: automatic creation of a CNAME if CNAME option is true, from the config url
• postbuild: create a .nojekyll file if “nojekyll” is true (default) (src/builder/post-build
• logs show elapsed time by default
• dev server show a page saying that JS is required (see src/builder/server)
• hot loading for modules AND collection content
• webpack logs are limited by default to avoid noize
• “/stuff/index.html” works during development (custom "route: file.html" in mardown front-fatter don't work during development #808)
• dev server default page show JS error if one occurs (see src/builder/server)
• dev server handle occupied ports - if default phenomic ports is not free, we should ask user to double check and offer to use another one (like CRA)
• react-router scroll mess is handled (see src/client/should-update-scroll.js)
• glamor & aphrodite should be handled or VERY easy to enable
• react-helmet should be handled (and/or see next.js head feature)
• Link handle / & /index.html as a same url for activeState
• Link should handle local and external link (so you can reference a dynamic value (eg from front-matter) using Link - see src/components/Link)
• optimistic loading/layout & shit (see src/components/PageContainer) - big deal here
• all the configurations is validated and you get proper warnings if incorrect (see src/configurator)
• all options! src/configurator/definitions.js
• offer helper to retrieve collections data (I guess it’s done already :) )
• base theme offer a package for a recommended eslint config, recommended stylelint config
• provide a good default for markdown transformation (see src/loader-plugin-*)
• easy rss & sitemap
• ability to define routes (eg: tags/:tag) with pagination
• we should keep or base theme, people seems to like it
• good docs!

“Developer features”

• npm or yarn can be used (even if npm is slower and less predictable)
• project is run on travis for yarn, circle ci for npm and appveyor for windows/npm
• project CI should run unit test + build docs + build a new project using the setup and run some end to end test (see e2e-tests)

[MoOx]

Obviously, feel free to discuss this list ;)

[MoOx]

It has begun... #936
Feel free to continue the discussion over there!

[MoOx]

Next.js has now a open PR to add next export, time to check again if that's interesting to rely on it.

vercel/next.js#1576

That would be awesome to rely on next which (I think) will have a bright future.

[MoOx]

Relying on next.js is not a priority, we might add a plugin for this later.

[MoOx]

master is a 1.0.0 super pre alpha, we might release an official alpha/beta at the end of the month.