Programmatic API #310

nkzawa · 2016-11-30T04:07:14Z

Fixes #291

support hot-code reloading even on custom routes
enable to use high and low level APIs depends on your needs

Ideas are basically the same with #291, but some APIs are a bit different.

API

next({ dir = '.', dev = false } = {})

const next from 'next'
const app = next()

app.render(req, res, pathname, query) - renders pathname and automatically handle response. renders /_error and set status code to res.statusCode if an error occurred.
app.renderToHTML(req, res, pathname, query) - similar to app.render but doesn't automatically handle response and returns a Promise of html string.
app.renderError(err, req, res, pathname, query) - similar to app.render but renders /_error (or the error page for debug if dev is true).
app.renderErrorToHTML(err, req, res, pathname, query) - similar to app.renderError but doesn't automatically handle response and returns a Promise of html string.
app.prepare() - wait to be prepared for serving.

Link

It takes a new prop as which is url value and href represents the path for the page component if as exists.

For example, it fetches the /foo component and url transitions to /bar if you click the following link.

<Link href="/foo" as="/bar">here</Link>

arunoda · 2016-11-30T04:21:36Z

examples/custom-server/server.js

+  createServer((req, res) => {
+    const accept = accepts(req)
+    const type = accept.type(['json', 'html'])
+    if (type === 'json') {


I didn't read the code in full, why do we need to do this?
If that's related to our .json file serving, can't app.render() could check the accept type and do something about it?

The idea is user has nothing to worry about our .json file serving?

This is actually for .json file serving which is changed to use the Accept header with this PR.
The main reason we don't serve it using app.render is JSON endpoint for a component should be only one, so that you can use <Link href="/foo" as="/bar"> easier, for example.
Another reason is we have app.renderToHTML method too which you'd have to check the Accept header for using it anyway.
But I think it's arguable. Let me know if you have any ideas.

Actually, my idea to remove this overhead from the user.

Anyway do we need to do this:

<Link href="/foo" as="/bar">

Since we are defining routes on the server. I think client doesn't need to know about anything about the actual mapping. So could do this:

<Link href="/blog/postId">

If we can somehow do this, this will be awesome.

<Link href="/foo" as="/bar"> is for caching. A JSON response for a component is always identical, so we want to allow only <Link href="/blog" as="/blog/123"> instead of <Link href="/blog/123">

Okay. That makes sense.

@nkzawa @rauchg how about on the other way.
Usually href means the URL display in the browser. So, how about something like this:

<Link href="/blog/123" for="/blog">

I like as for it implies decoration. We could also call it display?

I also feel this is a bit confusing since href is an existing prop which we give a different meaning.

nkzawa · 2016-12-01T03:23:30Z

examples/custom-server/pages/index.js

+export default () => (
+  <ul>
+    <li><Link href='/b' as='/a'><a>a</a></Link></li>
+    <li><Link href='/a' as='/b'><a>b</a></Link></li>


I think we should replace as with pathname, route or something like that, since you'd always like to write actual url to href.

I add some comments here about Link: #310 (comment)

I am not sure how to do this, but if we could find to use just <Link href='xxx'/> on the client that would be awesome.

nkzawa · 2016-12-01T03:29:06Z

examples/custom-server/server.js

+app.prepare()
+.then(() => {
+  createServer((req, res) => {
+    const accept = accepts(req)


This means parsing the Accept header can happen twice, since we do it in our handler too :(

@nkzawa can't handle have an optional 3rd argument for parsing accept header, so that we just going to have to parse it once?

That sounds good. Alternatively, we can have two handlers, one is for JSON, the other is for HTML.

nkzawa · 2016-12-01T03:31:48Z

server/index.js

 import HotReloader from './hot-reloader'
 import { resolveFromList } from './resolve'

 export default class Server {
-  constructor ({ dir = '.', dev = false, hotReload = false }) {


hotReload option is removed since only dev: true, hotReload: true or dev: false, hotReload: false work for now anyway.

I really like this.
I don't think there's a much of a use case for dev: false and hotReload: true

We may need to enable hotReload in production for mobile apps, but we could do it later.

I agree with @arunoda. Very cool simplification

nkzawa · 2016-12-01T03:40:27Z

examples/custom-server/server.js

+const app = next('.', { dev: true })
+const handle = app.getRequestHandler()
+
+app.prepare()


We have to wait app ready.

nkzawa · 2016-12-01T06:42:53Z

server/next.js

+import Server from './'
+
+module.exports = (dir, opts) => {
+  return new Server(dir, opts)


I wonder if we can make dir optional and default to . (current directory).

@nkzawa please

jaredpalmer · 2016-12-01T21:11:12Z

examples/custom-server/server.js

+      app.render(req, res, '/b', query)
+    } else if (pathname === '/b') {
+      app.render(req, res, '/a', query)
+    } else {


In addition to this basic switching, I think the example should also explicitly show how to make a parameterized route (e.g. /blog/:id). IMHO, this will mitigate tons of questions/confusion.

This is awesome btw!

+1 @jaredpalmer. We should have a basic example and a route pattern matching example

@rauchg maybe i'm confused, but how do you get the params to the react page after matching on the server? this.props.url.params?

My temporary workaround is this:

let { pathname, query } = parse(req.url, true) if (route('/blog/:id')(pathname).id) { query = query || {} query.params = route('/blog/:id')(pathname) app.render(req, res, '/blog__id', query) } else { handle(req, res) }

I feel like app.render should accept an optional params argument that gets passed into getInitialProps(ctx)?

I think that was our plan @nkzawa?

yep, that's the recommended way.

the example of parameterized routing was added.

@rauchg @nkzawa The Link implementation prevents access to the "desired" window object on the client of the decorated route during getInitialProps. You can test this by logging window.location in and out of getInitialProps and following a Link. The window.location will represent that of the href and not as, so things like are not accessible for data fetching. In contrast, the back button will give you the "correct" window.location during getInitialProps because it is a full render. Thoughts?

ping @nkzawa @rauchg ^^

@jaredpalmer you can use pathname and query arguments of getInitialProps instead of window.location.

coveralls · 2016-12-02T10:19:20Z

Coverage increased (+11.0%) to 48.234% when pulling 849029d on add/programmatic-api into ea5ec12 on master.

coveralls · 2016-12-02T10:31:09Z

Coverage increased (+11.0%) to 48.234% when pulling 302fe60 on add/programmatic-api into ea5ec12 on master.

coveralls · 2016-12-03T19:25:27Z

Coverage increased (+11.0%) to 48.234% when pulling 147b647 on add/programmatic-api into ea5ec12 on master.

coveralls · 2016-12-03T20:22:30Z

Coverage increased (+11.0%) to 48.234% when pulling d853586 on add/programmatic-api into ea5ec12 on master.

nkzawa · 2016-12-03T20:42:57Z

examples/custom-server/server.js

+      return
+    }
+
+    const { pathname, query } = parse(req.url, true)


Parsing url also can happen multiple times :(
Maybe handle should take pathname and query as optional arguments ?

handle(req, res, pathname, query)

+1 for this since its opt-in it wouldn't affect simplicity of the API.

@nkzawa or pass the un-destructured url object?

handle(req, res, pathname, query) seems better since it's same arguments with app.render().
But on handle(), we don't want to allow customizing pathname and query like app.render(), so un-destructured url object also makes sense, umm.

coveralls · 2016-12-06T13:05:42Z

Coverage increased (+11.02%) to 48.229% when pulling 4fe3ba8 on add/programmatic-api into 7086287 on master.

coveralls · 2016-12-08T11:01:43Z

Coverage increased (+11.02%) to 48.229% when pulling cc25662 on add/programmatic-api into 249a0c4 on master.

knpwrs · 2016-12-12T16:47:29Z

#370 mentioned being able to use a database via a programmatic API. How would that work with this PR as it stands? My thought would have been some sort of way to pass data into the root react component or to define isServer and isClient variables via webpack that could then enable code trimming via uglify-js.

queso · 2016-12-12T18:41:23Z

Waiting on this to port a site to Next... What else is left here @nkzawa or @rauchg?

* Add custom-server-express example * Remove extraneous nexts in express routes defs * Update next config in server.js

sarukuku · 2016-12-15T14:26:14Z

I'd ❤️ to see this land soon.

* Handle accept headers totally inside Next.js Now user doesn't need to handle it anymore. * Move json pages serving to /_next/pages base path. * Join paths correctly.

* fixed bug #362, also set chunks names * set simple solution for minChunks * revert in favor of #310

jamiebuilds · 2016-12-19T00:14:44Z

package.json

@@ -2,7 +2,7 @@
  "name": "next",
  "version": "1.2.3",
  "description": "Minimalistic framework for server-rendered React applications",
-  "main": "./dist/lib/index.js",
+  "main": "./dist/server/next.js",


This appears to be incorrect. Looks like it should be ./dist/server/index.js

$ ls node_modules/next/dist/server build config.js hot-reloader.js index.js read.js render.js require.js resolve.js router.js

never mind I see you haven't published a new version

jamiebuilds · 2016-12-19T00:17:00Z

examples/parameterized-routing/server.js

+const next = require('next')
+const pathMatch = require('path-match')
+
+const app = next({ dev: true })


Based on https://github.com/zeit/next.js/pull/310/files#r92954990, looking at ./dist/server/index.js the api seems to require new next({...}) to create the server.

oh never mind I see you haven't published a new version

ijjk · 2020-03-10T18:35:08Z

Failing test suites

test/integration/app-document/test/index.test.js

Document and App > Client side > should detect the changes to pages/_document.js and display it

Expand output

● Document and App › Client side › should detect the changes to pages/_document.js and display it

TIMED OUT: /Hello Document HMR/

Hello Document
Hi Document HMR
Hello App
Hello HMR
0.8709149041435691
index
about

  327 |     }
  328 |     console.error('TIMED OUT CHECK: ', { regex, content })
> 329 |     throw new Error('TIMED OUT: ' + regex + '\n\n' + content)
      |           ^
  330 |   }, 1000 * 30)
  331 |   while (!found) {
  332 |     try {

  at Timeout._onTimeout (lib/next-test-utils.js:329:11)

nkzawa added 11 commits November 25, 2016 01:48

add 'next' api

9639a89

add render APIs

ce28515

add 'as' prop to Link

136cf53

check Accept header to serve json response

deeb8ea

check if response was finished on getInitialProps call

0e08598

move server/app to server/index

e2c2ded

load webpack-hot-middleware-client by absolute path

ae33b83

server: options for testing

3401a75

add tests

b2e5738

example: improve

cf5497c

Merge branch 'master' into add/programmatic-api

297ed1d

arunoda reviewed Nov 30, 2016

View reviewed changes

nkzawa commented Dec 1, 2016

View reviewed changes

jaredpalmer reviewed Dec 1, 2016

View reviewed changes

arunoda mentioned this pull request Dec 2, 2016

Exploration of different config + expose webpack config #222

Merged

rauchg mentioned this pull request Dec 2, 2016

Programmatic API #291

Closed

Merge branch 'master' into add/programmatic-api

849029d

server: make dir optional

302fe60

nkzawa added 2 commits December 4, 2016 04:18

fix client routing

a412362

add parameterized routing example

147b647

link: fix display url

d853586

nkzawa commented Dec 3, 2016

View reviewed changes

Merge branch 'master' into add/programmatic-api

4fe3ba8

jaredpalmer mentioned this pull request Dec 6, 2016

Add custom-server-express example #352

Merged

Merge branch 'master' into add/programmatic-api

cc25662

arunoda mentioned this pull request Dec 10, 2016

Prefetch pages with Service Workers #375

Merged

Add custom-server-express example (#352)

8318728

* Add custom-server-express example * Remove extraneous nexts in express routes defs * Update next config in server.js

This was referenced Dec 15, 2016

expose new setHeaders API #391

Closed

fixed bug #362, also set chunks names #363

Merged

mr47 added a commit to mr47/next.js that referenced this pull request Dec 15, 2016

revert in favor of vercel#310

e387731

Handle accept headers totally inside Next.js (#385)

4508725

* Handle accept headers totally inside Next.js Now user doesn't need to handle it anymore. * Move json pages serving to /_next/pages base path. * Join paths correctly.

arunoda pushed a commit that referenced this pull request Dec 15, 2016

fixed bug #362, also set chunks names (#363)

45e36fd

* fixed bug #362, also set chunks names * set simple solution for minChunks * revert in favor of #310

This was referenced Dec 15, 2016

Make the Programmatic API aware of prefetching #400

Closed

How to write Server Side Code? #404

Closed

nkzawa added 2 commits December 17, 2016 04:20

Merge branch 'master' into add/programmatic-api

8bcfbe6

remove next/render

0af7355

rauchg merged commit 1708222 into master Dec 16, 2016

rauchg deleted the add/programmatic-api branch December 16, 2016 20:33

backflip mentioned this pull request Dec 17, 2016

Allow for custom route in pushTo and replaceTo methods #417

Merged

This was referenced Dec 17, 2016

Routing questions - params patterns like: "/profile/:id/edit" and server db -how to pass data to react components? #418

Closed

Add X-Powered-By header. #416

Merged

mr47 mentioned this pull request Dec 17, 2016

How to load external assets only once accross isomorphic navigation? #373

Closed

jamiebuilds reviewed Dec 19, 2016

View reviewed changes

arunoda mentioned this pull request Dec 19, 2016

Implement the Singleton Router API #429

Merged

lock bot locked as resolved and limited conversation to collaborators Jan 19, 2019

Programmatic API #310

Programmatic API #310

Conversation

nkzawa commented Nov 30, 2016 • edited Loading

API

next({ dir = '.', dev = false } = {})

Link

arunoda Nov 30, 2016 • edited Loading

Choose a reason for hiding this comment

nkzawa Dec 1, 2016 • edited Loading

Choose a reason for hiding this comment

arunoda Dec 1, 2016 • edited Loading

Choose a reason for hiding this comment

nkzawa Dec 1, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arunoda Dec 2, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nkzawa Dec 1, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chiefjester Dec 2, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jaredpalmer Dec 2, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Dec 2, 2016 • edited Loading

coveralls commented Dec 2, 2016 • edited Loading

coveralls commented Dec 3, 2016 • edited Loading

coveralls commented Dec 3, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Dec 6, 2016 • edited Loading

coveralls commented Dec 8, 2016 • edited Loading

knpwrs commented Dec 12, 2016

queso commented Dec 12, 2016

sarukuku commented Dec 15, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ijjk commented Mar 10, 2020

Failing test suites

nkzawa commented Nov 30, 2016 •

edited

Loading

arunoda Nov 30, 2016 •

edited

Loading

nkzawa Dec 1, 2016 •

edited

Loading

arunoda Dec 1, 2016 •

edited

Loading

nkzawa Dec 1, 2016 •

edited

Loading

arunoda Dec 2, 2016 •

edited

Loading

nkzawa Dec 1, 2016 •

edited

Loading

chiefjester Dec 2, 2016 •

edited

Loading

jaredpalmer Dec 2, 2016 •

edited

Loading

coveralls commented Dec 2, 2016 •

edited

Loading

coveralls commented Dec 2, 2016 •

edited

Loading

coveralls commented Dec 3, 2016 •

edited

Loading

coveralls commented Dec 3, 2016 •

edited

Loading

coveralls commented Dec 6, 2016 •

edited

Loading

coveralls commented Dec 8, 2016 •

edited

Loading